pdrng 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+When contributing to this repository, please first discuss the change you wish to make via issue,
+email, or any other method with the owners of this repository before making a change.
+
+## Pull Request Process
+
+1. Ensure any install or build dependencies are removed before the end of the layer when doing a
+   build.
+2. Update the README.md with details of changes to the interface, this includes new environment
+   variables, exposed ports, useful file locations and container parameters.
+3. Increase the version numbers in any examples files and the README.md to the new version that this
+   Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
+4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you
+   do not have permission to do that, you may request the second reviewer to merge it for you.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Funk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+[![pdrng](https://img.shields.io/badge/pdrng-Deterministic%20RNG-b5d4ff.svg)](https://github.com/brianfunk/pdrng)
+[![npm version](https://img.shields.io/npm/v/pdrng.svg)](https://www.npmjs.com/package/pdrng)
+[![npm downloads](https://img.shields.io/npm/dm/pdrng.svg)](https://www.npmjs.com/package/pdrng)
+[![CI](https://github.com/brianfunk/pdrng/actions/workflows/ci.yml/badge.svg)](https://github.com/brianfunk/pdrng/actions/workflows/ci.yml)
+[![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badge/)
+[![Semver](https://img.shields.io/badge/SemVer-2.0-blue.svg)](http://semver.org/spec/v2.0.0.html)
+[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://opensource.org/licenses/MIT)
+[![LinkedIn](https://img.shields.io/badge/Linked-In-blue.svg)](https://www.linkedin.com/in/brianrandyfunk)
+
+# pdrng
+
+> Pseudo Deterministic Random Number Generator — seed-based deterministic number generation.
+
+A JavaScript library for generating deterministic outputs based on a numeric seed. Given the same seed, every function produces the same result every time. Useful for testing, simulations, reproducible demos, and seeded content generation.
+
+**Default seed: 814**
+
+## Install
+
+```bash
+npm install pdrng
+```
+
+## Quick Start
+
+```javascript
+import pdrng from 'pdrng';
+
+pdrng()        // 814
+pdrng(1)       // 8
+pdrng(6)       // 814814
+pdrng.coin()   // "tails"
+pdrng.dice()   // 4
+pdrng.card()   // "8 of Diamonds"
+```
+
+## API
+
+### Core
+
+#### `pdrng(digits?, options?)`
+
+Generate a deterministic number with the specified number of digits.
+
+```javascript
+pdrng()           // 814 (default: 3 digits)
+pdrng(1)          // 8
+pdrng(2)          // 14
+pdrng(4)          // 8148
+pdrng(5)          // 81414
+pdrng(6)          // 814814
+```
+
+### Utilities
+
+#### `float(precision?, options?)`
+
+```javascript
+float()           // 0.814814
+float(3)          // 0.814
+```
+
+#### `range(min, max, options?)`
+
+```javascript
+range(1, 100)     // 14
+```
+
+#### `array(count, digits?, options?)`
+
+```javascript
+array(3, 2)       // [14, 46, 78] (sub-seeds per element)
+```
+
+#### `uuid(options?)`
+
+```javascript
+uuid()            // deterministic UUID v4 format
+```
+
+#### `oddOrEven(options?)`
+
+```javascript
+oddOrEven()       // "even"
+```
+
+#### `redOrBlack(options?)`
+
+```javascript
+redOrBlack()      // "red"
+```
+
+#### `randomSeed()`
+
+Generate a random seed using `crypto.getRandomValues` (with `Math.random` fallback).
+
+```javascript
+randomSeed()      // e.g. 3847291056 (different each call)
+```
+
+### Simulation Functions
+
+#### `coin(options?)`
+
+Deterministic coin flip.
+
+```javascript
+coin()            // "tails"
+```
+
+#### `dice(sides?, options?)`
+
+Deterministic die result.
+
+```javascript
+dice()            // 4 (6-sided)
+dice(20)          // 14
+```
+
+#### `card(options?)`
+
+Deterministic playing card draw.
+
+```javascript
+card()            // "8 of Diamonds"
+```
+
+#### `rps(options?)`
+
+Deterministic rock-paper-scissors.
+
+```javascript
+rps()             // "scissors"
+```
+
+#### `magic8(options?)`
+
+Deterministic 8-ball response.
+
+```javascript
+magic8()          // "Reply hazy, try again."
+```
+
+#### `zodiac(options?)`
+
+Deterministic zodiac sign.
+
+```javascript
+zodiac()          // "Gemini"
+```
+
+#### `tarot(options?)`
+
+Deterministic tarot card.
+
+```javascript
+tarot()           // "The Magician"
+```
+
+#### `fortune(options?)`
+
+Deterministic fortune message.
+
+```javascript
+fortune()         // "The answer you seek was never in doubt."
+```
+
+#### `spin(array, options?)`
+
+Deterministic selection from an array.
+
+```javascript
+spin(['a', 'b', 'c', 'd'])  // "c"
+```
+
+#### `roll(notation, options?)`
+
+Deterministic dice notation result (tabletop RPG style).
+
+```javascript
+roll('2d6+3')     // { rolls: [5, 1], modifier: 3, total: 9 }
+```
+
+#### `bingo(options?)`
+
+Deterministic bingo call.
+
+```javascript
+bingo()           // "B-14"
+```
+
+#### `color(options?)`
+
+Deterministic hex color.
+
+```javascript
+color()           // "#a81414"
+```
+
+#### `roulette(options?)`
+
+Deterministic number with color and parity.
+
+```javascript
+roulette()        // { number: 14, color: "red", parity: "even" }
+```
+
+## Custom Seeds
+
+Every function accepts an `options` object with a `seed` property:
+
+```javascript
+import { coin, dice, card } from 'pdrng';
+
+coin({ seed: 42 })        // "heads"
+dice(6, { seed: 42 })     // 4
+card({ seed: 'brian' })   // deterministic card from text seed
+```
+
+Text seeds are converted using a rolling XOR hash, designed so that `"brian"` maps to seed 814:
+
+```javascript
+pdrng(3, { seed: 'brian' })  // 814 (same as default!)
+pdrng(4, { seed: 'brian' })  // 8148
+```
+
+## Random Seeds
+
+While pdrng is deterministic by design, you can use random input to get non-deterministic behavior. Pass `Math.random()`, `crypto.getRandomValues()`, or use the built-in `randomSeed()` helper:
+
+```javascript
+import { coin, dice, randomSeed } from 'pdrng';
+
+// Built-in helper (uses crypto.getRandomValues for real entropy)
+coin({ seed: randomSeed() })      // different each call
+
+// Math.random() works directly as a seed
+dice(6, { seed: Math.random() })  // different each call
+```
+
+## Imports
+
+```javascript
+// Default import (with all methods attached)
+import pdrng from 'pdrng';
+pdrng.coin();
+
+// Named imports
+import { coin, dice, card, roll } from 'pdrng';
+coin();
+```
+
+## Requirements
+
+- Node.js 18+
+- ESM only (`import`/`export`)
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,716 @@
+/**
+ *            _
+ *  _ __   __| |_ __ _ __   __ _
+ * | '_ \ / _` | '__| '_ \ / _` |
+ * | |_) | (_| | |  | | | | (_| |
+ * | .__/ \__,_|_|  |_| |_|\__, |
+ * |_|                      |___/
+ *
+ * pdrng - Pseudo Deterministic Random Number Generator
+ *
+ * A seed-based deterministic number generator.
+ * All outputs are fully reproducible given the same seed (default: 814).
+ *
+ * @module pdrng
+ * @version 1.0.0
+ * @license MIT
+ * @author Brian Funk
+ */
+
+// ─── Default Seed ────────────────────────────────────────────────────────────
+
+const DEFAULT_SEED = 814;
+
+// ─── Private Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Convert a text string to a numeric seed.
+ * Rolling XOR hash: each character mixes with the running hash via XOR shift.
+ * Formula: 2 * (rollingHash + length), where rollingHash starts at 3.
+ * Designed so that "brian" → 814.
+ * @param {string} text
+ * @returns {number}
+ */
+const _textToSeed = (text) => {
+  const str = String(text);
+  let hash = 3;
+  for (let i = 0; i < str.length; i++) {
+    hash = hash + (str.charCodeAt(i) ^ (hash >> 2));
+  }
+  return 2 * (hash + str.length);
+};
+
+/**
+ * Normalize a seed value to a positive integer.
+ * Strings are converted via _textToSeed, numbers are floored and abs'd.
+ * @param {number|string} seed
+ * @returns {number}
+ */
+const _normalizeSeed = (seed) => {
+  if (seed === undefined || seed === null) return DEFAULT_SEED;
+  if (typeof seed === 'string') return _textToSeed(seed);
+  const num = Number(seed);
+  if (!Number.isFinite(num)) return DEFAULT_SEED;
+  const abs = Math.abs(num);
+  // Handle floats between 0 and 1 (e.g. Math.random()) by scaling up
+  if (abs > 0 && abs < 1) {
+    const str = String(abs).replace('0.', '');
+    return Number(str) || DEFAULT_SEED;
+  }
+  const n = Math.floor(abs);
+  return n === 0 ? DEFAULT_SEED : n;
+};
+
+/**
+ * Get the array of digits from a seed.
+ * @param {number} seed
+ * @returns {number[]}
+ */
+const _digits = (seed) => String(seed).split('').map(Number);
+
+/**
+ * Sum of all digits.
+ * @param {number} seed
+ * @returns {number}
+ */
+const _digitSum = (seed) => _digits(seed).reduce((a, b) => a + b, 0);
+
+/**
+ * Product of all digits.
+ * @param {number} seed
+ * @returns {number}
+ */
+const _digitProduct = (seed) => _digits(seed).reduce((a, b) => a * b, 1);
+
+/**
+ * First digit of the seed.
+ * @param {number} seed
+ * @returns {number}
+ */
+const _firstDigit = (seed) => _digits(seed)[0];
+
+/**
+ * Last digit of the seed.
+ * @param {number} seed
+ * @returns {number}
+ */
+const _lastDigit = (seed) => {
+  const d = _digits(seed);
+  return d[d.length - 1];
+};
+
+/**
+ * Last N digits of the seed as a number.
+ * @param {number} seed
+ * @param {number} n
+ * @returns {number}
+ */
+const _lastN = (seed, n) => {
+  const str = String(seed);
+  if (n >= str.length) return seed;
+  return Number(str.slice(-n));
+};
+
+/**
+ * Digit-fill algorithm: produce a number with exactly `count` digits
+ * derived deterministically from the seed.
+ *
+ * Rules:
+ * - count < seed length: 1 digit → first digit, else last N digits
+ * - count = seed length: full seed
+ * - count > seed length: repeat full seed, remainder uses 1 char = first digit, 2+ chars = last N
+ *
+ * @param {number} seed
+ * @param {number} count
+ * @returns {number}
+ */
+const _fillDigits = (seed, count) => {
+  const seedStr = String(seed);
+  const seedLen = seedStr.length;
+
+  if (count <= 0) return 0;
+
+  if (count < seedLen) {
+    if (count === 1) return _firstDigit(seed);
+    return _lastN(seed, count);
+  }
+
+  if (count === seedLen) return seed;
+
+  // count > seedLen: repeat seed, then fill remainder
+  let result = '';
+  const fullRepeats = Math.floor(count / seedLen);
+  const remainder = count % seedLen;
+
+  for (let i = 0; i < fullRepeats; i++) {
+    result += seedStr;
+  }
+
+  if (remainder > 0) {
+    if (remainder === 1) {
+      result += String(_firstDigit(seed));
+    } else {
+      result += String(_lastN(seed, remainder));
+    }
+  }
+
+  return Number(result);
+};
+
+/**
+ * Build a priority list of values derived from the seed.
+ * Order: full seed, last N-1 digits ... last 2 digits, first digit, last digit, middle digits L→R.
+ *
+ * @param {number} seed
+ * @returns {number[]}
+ */
+const _seedPriority = (seed) => {
+  const seedStr = String(seed);
+  const n = seedStr.length;
+  const values = [seed];
+
+  // Last N-1 down to last 2 digits
+  for (let i = n - 1; i >= 2; i--) {
+    values.push(Number(seedStr.slice(-i)));
+  }
+
+  // First digit
+  values.push(Number(seedStr[0]));
+
+  // Last digit
+  if (n > 1) {
+    values.push(Number(seedStr[n - 1]));
+  }
+
+  // Remaining middle digits, left to right
+  for (let i = 1; i < n - 1; i++) {
+    values.push(Number(seedStr[i]));
+  }
+
+  return values;
+};
+
+/**
+ * Select a value from [min, max] using the seed priority algorithm.
+ * Returns the first priority value that falls within [min, max].
+ * Falls back to modulo-based selection if no priority value fits.
+ *
+ * @param {number} seed
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+const _selectFromRange = (seed, min, max) => {
+  const priorities = _seedPriority(seed);
+  for (const val of priorities) {
+    if (val >= min && val <= max) {
+      return val;
+    }
+  }
+  return min + (seed % (max - min + 1));
+};
+
+// ─── Data Constants ──────────────────────────────────────────────────────────
+
+const MAGIC_8_RESPONSES = Object.freeze([
+  'It is certain.',
+  'It is decidedly so.',
+  'Without a doubt.',
+  'Yes — definitely.',
+  'You may rely on it.',
+  'As I see it, yes.',
+  'Most likely.',
+  'Outlook good.',
+  'Yes.',
+  'Signs point to yes.',
+  'Reply hazy, try again.',
+  'Ask again later.',
+  'Better not tell you now.',
+  'Cannot predict now.',
+  'Reply hazy, try again.',
+  'Don\'t count on it.',
+  'My reply is no.',
+  'My sources say no.',
+  'Outlook not so good.',
+  'Very doubtful.'
+]);
+
+const MAJOR_ARCANA = Object.freeze([
+  'The Magician',
+  'The High Priestess',
+  'The Empress',
+  'The Emperor',
+  'The Hierophant',
+  'The Lovers',
+  'The Chariot',
+  'Strength',
+  'The Hermit',
+  'Wheel of Fortune',
+  'Justice',
+  'The Hanged Man',
+  'Death',
+  'Temperance',
+  'The Devil',
+  'The Tower',
+  'The Star',
+  'The Moon',
+  'The Sun',
+  'Judgement',
+  'The World',
+  'The Fool'
+]);
+
+const FORTUNES = Object.freeze([
+  'A beautiful, smart, and loving person will be coming into your life.',
+  'A dubious friend may be an enemy in camouflage.',
+  'A faithful friend is a strong defense.',
+  'A feather in the hand is better than a bird in the air.',
+  'A fresh start will put you on your way.',
+  'A golden egg of opportunity falls into your lap this month.',
+  'A good friendship is often more important than a passionate romance.',
+  'A good time to finish up old tasks.',
+  'A lifetime friend shall soon be made.',
+  'A lifetime of happiness lies ahead of you.',
+  'A light heart carries you through all the hard times.',
+  'A new perspective will come with the new year.',
+  'A pleasant surprise is waiting for you.',
+  'The answer you seek was never in doubt.',
+  'A smile is your passport into the hearts of others.',
+  'A smooth long journey! Great expectations.',
+  'A soft voice may be awfully persuasive.',
+  'A true friend is the best possession.',
+  'Accept something that you cannot change, and you will feel better.',
+  'All the effort you are making will ultimately pay off.'
+]);
+
+const SUITS = Object.freeze(['Spades', 'Diamonds', 'Hearts', 'Clubs']);
+
+const RANKS = Object.freeze([
+  'Ace', '2', '3', '4', '5', '6', '7', '8', '9', '10',
+  'Jack', 'Queen', 'King'
+]);
+
+const RPS_OPTIONS = Object.freeze(['rock', 'paper', 'scissors']);
+
+const COIN_SIDES = Object.freeze(['heads', 'tails']);
+
+const BINGO_LETTERS = Object.freeze(['B', 'I', 'N', 'G', 'O']);
+
+const RED_NUMBERS = Object.freeze([
+  1, 3, 5, 7, 9, 12, 14, 16, 18, 19, 21, 23, 25, 27, 30, 32, 34, 36
+]);
+
+const ZODIAC_SIGNS = Object.freeze([
+  { name: 'Aries', month: 3, startDay: 21 },
+  { name: 'Taurus', month: 4, startDay: 20 },
+  { name: 'Gemini', month: 5, startDay: 21 },
+  { name: 'Cancer', month: 6, startDay: 21 },
+  { name: 'Leo', month: 7, startDay: 23 },
+  { name: 'Virgo', month: 8, startDay: 23 },
+  { name: 'Libra', month: 9, startDay: 23 },
+  { name: 'Scorpio', month: 10, startDay: 23 },
+  { name: 'Sagittarius', month: 11, startDay: 22 },
+  { name: 'Capricorn', month: 12, startDay: 22 },
+  { name: 'Aquarius', month: 1, startDay: 20 },
+  { name: 'Pisces', month: 2, startDay: 19 }
+]);
+
+// ─── Core Function ───────────────────────────────────────────────────────────
+
+/**
+ * Generate a deterministic "random" number with the specified number of digits.
+ *
+ * @param {number} [digits=3] - Number of digits in the result
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {number}
+ */
+const pdrng = (digits = 3, options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return _fillDigits(seed, digits);
+};
+
+// ─── Utility Functions ───────────────────────────────────────────────────────
+
+/**
+ * Generate a deterministic float between 0 and 1.
+ *
+ * @param {number} [precision=6] - Number of decimal places
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {number}
+ */
+const float = (precision = 6, options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const filled = _fillDigits(seed, precision);
+  return Number('0.' + String(filled).padStart(precision, '0'));
+};
+
+/**
+ * Generate a deterministic integer within a range (inclusive).
+ *
+ * @param {number} min - Minimum value
+ * @param {number} max - Maximum value
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {number}
+ */
+const range = (min, max, options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return _selectFromRange(seed, min, max);
+};
+
+/**
+ * Generate an array of deterministic numbers.
+ * Each element uses a sub-seed derived from the main seed + index.
+ *
+ * @param {number} count - Number of elements
+ * @param {number} [digits=3] - Digits per element
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {number[]}
+ */
+const array = (count, digits = 3, options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const result = [];
+  for (let i = 0; i < count; i++) {
+    const subSeed = seed + i * _digitProduct(seed);
+    result.push(_fillDigits(_normalizeSeed(subSeed), digits));
+  }
+  return result;
+};
+
+/**
+ * Generate a deterministic UUID (v4 format).
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string}
+ */
+const uuid = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const ds = _digitSum(seed);
+  const dp = _digitProduct(seed);
+  const fd = _firstDigit(seed);
+  const ld = _lastDigit(seed);
+
+  // Build 32 hex chars deterministically
+  const sources = [seed, ds, dp, fd, ld, seed + ds, seed + dp, seed * fd];
+  let hex = '';
+  for (const src of sources) {
+    let val = Math.abs(src);
+    for (let i = 0; i < 4; i++) {
+      hex += ((val + i * 7) % 16).toString(16);
+    }
+  }
+
+  // Format as UUID v4: xxxxxxxx-xxxx-4xxx-Nxxx-xxxxxxxxxxxx
+  hex = hex.slice(0, 32);
+  const chars = hex.split('');
+  chars[12] = '4'; // version 4
+  const n = (8 + (_digitSum(seed) % 4)); // variant: 8, 9, a, or b
+  chars[16] = n.toString(16);
+
+  return [
+    chars.slice(0, 8).join(''),
+    chars.slice(8, 12).join(''),
+    chars.slice(12, 16).join(''),
+    chars.slice(16, 20).join(''),
+    chars.slice(20, 32).join('')
+  ].join('-');
+};
+
+/**
+ * Determine if the seed is odd or even.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} "odd" or "even"
+ */
+const oddOrEven = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return seed % 2 === 0 ? 'even' : 'odd';
+};
+
+/**
+ * Determine red or black based on digit sum.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} "red" or "black"
+ */
+const redOrBlack = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return _digitSum(seed) % 2 === 1 ? 'red' : 'black';
+};
+
+/**
+ * Generate a random seed using crypto for true entropy.
+ * Pass the result as { seed: randomSeed() } to any pdrng function
+ * for non-deterministic behavior.
+ *
+ * @returns {number}
+ */
+const randomSeed = () => {
+  if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
+    const buffer = new Uint32Array(1);
+    globalThis.crypto.getRandomValues(buffer);
+    return buffer[0] || DEFAULT_SEED;
+  }
+  // Fallback for environments without Web Crypto API
+  return Math.floor(Math.random() * 2147483647) || DEFAULT_SEED;
+};
+
+// ─── Simulation Functions ────────────────────────────────────────────────────
+
+/**
+ * Flip a deterministic coin.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} "heads" or "tails"
+ */
+const coin = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return COIN_SIDES[_digitSum(seed) % 2];
+};
+
+/**
+ * Roll a deterministic die.
+ *
+ * @param {number} [sides=6] - Number of sides
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {number} 1 to sides
+ */
+const dice = (sides = 6, options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return _selectFromRange(seed, 1, sides);
+};
+
+/**
+ * Draw a deterministic playing card.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} e.g. "8 of Diamonds"
+ */
+const card = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const rankIndex = (seed - 1) % 13;
+  const suitIndex = _digitSum(seed) % 4;
+  return `${RANKS[rankIndex]} of ${SUITS[suitIndex]}`;
+};
+
+/**
+ * Spin the roulette wheel deterministically.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {Object} { number, color, parity }
+ */
+const roulette = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const num = _lastN(seed, 2) % 37;
+
+  let color;
+  if (num === 0) {
+    color = 'green';
+  } else if (RED_NUMBERS.includes(num)) {
+    color = 'red';
+  } else {
+    color = 'black';
+  }
+
+  const parity = num === 0 ? 'zero' : (num % 2 === 0 ? 'even' : 'odd');
+
+  return { number: num, color, parity };
+};
+
+/**
+ * Play rock, paper, scissors deterministically.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} "rock", "paper", or "scissors"
+ */
+const rps = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return RPS_OPTIONS[_digitProduct(seed) % 3];
+};
+
+/**
+ * Shake the Magic 8-Ball deterministically.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string}
+ */
+const magic8 = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return MAGIC_8_RESPONSES[seed % 20];
+};
+
+/**
+ * Determine your deterministic zodiac sign.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} e.g. "Gemini"
+ */
+const zodiac = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const signIndex = _lastN(seed, 2) % 12;
+  return ZODIAC_SIGNS[signIndex].name;
+};
+
+/**
+ * Draw a deterministic tarot card (Major Arcana).
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string}
+ */
+const tarot = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return MAJOR_ARCANA[seed % 22];
+};
+
+/**
+ * Receive a deterministic fortune.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string}
+ */
+const fortune = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  return FORTUNES[_digitSum(seed) % 20];
+};
+
+/**
+ * Spin a wheel (pick from an array) deterministically.
+ *
+ * @param {Array} arr - Array of choices
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {*}
+ */
+const spin = (arr, options = {}) => {
+  if (!Array.isArray(arr) || arr.length === 0) {
+    throw new Error('spin() requires a non-empty array');
+  }
+  const seed = _normalizeSeed(options.seed);
+  return arr[seed % arr.length];
+};
+
+/**
+ * Roll dice using standard notation (e.g. "2d6+3").
+ *
+ * @param {string} notation - Dice notation like "2d6", "1d20+5", "3d8-2"
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {Object} { rolls, modifier, total }
+ */
+const roll = (notation, options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const match = String(notation).match(/^(\d+)d(\d+)([+-]\d+)?$/);
+  if (!match) {
+    throw new Error(`Invalid dice notation: "${notation}"`);
+  }
+
+  const count = parseInt(match[1], 10);
+  const sides = parseInt(match[2], 10);
+  const modifier = match[3] ? parseInt(match[3], 10) : 0;
+  const dp = _digitProduct(seed);
+
+  const rolls = [];
+  for (let i = 0; i < count; i++) {
+    const val = ((seed + i * dp) % sides) + 1;
+    rolls.push(val);
+  }
+
+  const total = rolls.reduce((a, b) => a + b, 0) + modifier;
+  return { rolls, modifier, total };
+};
+
+/**
+ * Call a bingo number deterministically.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} e.g. "B-14"
+ */
+const bingo = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const num = ((_lastN(seed, 2) - 1) % 75 + 75) % 75 + 1;
+  const letterIndex = Math.floor((num - 1) / 15);
+  return `${BINGO_LETTERS[letterIndex]}-${num}`;
+};
+
+/**
+ * Generate a deterministic hex color.
+ *
+ * @param {Object} [options={}] - Options
+ * @param {number|string} [options.seed] - Custom seed (default: 814)
+ * @returns {string} e.g. "#a81414"
+ */
+const color = (options = {}) => {
+  const seed = _normalizeSeed(options.seed);
+  const prefix = (_firstDigit(seed) + 2).toString(16);
+  const fill = String(_fillDigits(seed, 5));
+  return '#' + prefix + fill;
+};
+
+// ─── Attach Methods ──────────────────────────────────────────────────────────
+
+pdrng.float = float;
+pdrng.range = range;
+pdrng.array = array;
+pdrng.uuid = uuid;
+pdrng.oddOrEven = oddOrEven;
+pdrng.redOrBlack = redOrBlack;
+pdrng.coin = coin;
+pdrng.dice = dice;
+pdrng.card = card;
+pdrng.roulette = roulette;
+pdrng.rps = rps;
+pdrng.magic8 = magic8;
+pdrng.zodiac = zodiac;
+pdrng.tarot = tarot;
+pdrng.fortune = fortune;
+pdrng.spin = spin;
+pdrng.roll = roll;
+pdrng.bingo = bingo;
+pdrng.color = color;
+pdrng.randomSeed = randomSeed;
+pdrng.DEFAULT_SEED = DEFAULT_SEED;
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+export default pdrng;
+
+export {
+  pdrng,
+  float,
+  range,
+  array,
+  uuid,
+  oddOrEven,
+  redOrBlack,
+  coin,
+  dice,
+  card,
+  roulette,
+  rps,
+  magic8,
+  zodiac,
+  tarot,
+  fortune,
+  spin,
+  roll,
+  bingo,
+  color,
+  randomSeed,
+  DEFAULT_SEED
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pdrng",
+  "version": "1.0.0",
+  "description": "Pseudo Deterministic Random Number Generator - seed-based deterministic number generation",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint . --format stylish",
+    "lint:report": "eslint . --format html -o coverage/lint-report.html"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brianfunk/pdrng.git"
+  },
+  "keywords": [
+    "random",
+    "rng",
+    "prng",
+    "deterministic",
+    "seed",
+    "dice",
+    "coin",
+    "uuid",
+    "pseudo",
+    "number",
+    "generator"
+  ],
+  "author": "Brian Funk",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/brianfunk/pdrng/issues"
+  },
+  "homepage": "https://github.com/brianfunk/pdrng#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.17.0",
+    "vitest": "^4.0.18"
+  }
+}