@arcane-engine/runtime 0.1.0 → 0.2.1

package/src/rendering/text.ts

@@ -4,25 +4,41 @@ import { getCamera } from "./camera.ts";
 
 // --- Types ---
 
+/** Descriptor for a bitmap font backed by a texture atlas. */
 export type BitmapFont = {
+  /** Texture handle containing the font glyph atlas. */
   textureId: TextureId;
+  /** Width of each glyph cell in pixels. */
   glyphW: number;
+  /** Height of each glyph cell in pixels. */
   glyphH: number;
+  /** Number of glyph columns in the atlas. */
   columns: number;
+  /** Number of glyph rows in the atlas. */
   rows: number;
+  /** ASCII code of the first glyph in the atlas. Default: 32 (space). */
   firstChar: number;
 };
 
+/** Options for {@link drawText} and {@link measureText}. */
 export type TextOptions = {
+  /** Font to use. Default: built-in 8x8 CP437 bitmap font via getDefaultFont(). */
   font?: BitmapFont;
+  /** Scale multiplier for glyph size. Default: 1. A value of 2 draws at 16x16. */
   scale?: number;
+  /** RGBA tint color for the text (0.0-1.0 per channel). Default: white. */
   tint?: { r: number; g: number; b: number; a: number };
+  /** Draw order layer. Default: 100 (above most game sprites). */
   layer?: number;
+  /** If true, position is in screen pixels (HUD). If false, position is in world units. Default: false. */
   screenSpace?: boolean;
 };
 
+/** Result of {@link measureText}. Dimensions in pixels (before camera transform). */
 export type TextMeasurement = {
+  /** Total width in pixels (text.length * glyphW * scale). */
   width: number;
+  /** Total height in pixels (glyphH * scale). */
   height: number;
 };
 
@@ -54,6 +70,15 @@ let defaultFont: BitmapFont | null = null;
 
 /**
  * Create a bitmap font descriptor from a texture atlas.
+ * The atlas should contain a grid of equally-sized glyphs in ASCII order.
+ *
+ * @param textureId - Texture handle of the font atlas (from loadTexture()).
+ * @param glyphW - Width of each glyph cell in pixels.
+ * @param glyphH - Height of each glyph cell in pixels.
+ * @param columns - Number of glyph columns in the atlas.
+ * @param rows - Number of glyph rows in the atlas.
+ * @param firstChar - ASCII code of the first glyph in the atlas. Default: 32 (space).
+ * @returns BitmapFont descriptor for use with drawText().
  */
 export function loadFont(
   textureId: TextureId,
@@ -67,8 +92,10 @@ export function loadFont(
 }
 
 /**
- * Get the default 8x8 bitmap font, lazily initialized.
+ * Get the default built-in 8x8 CP437 bitmap font, lazily initialized.
  * In headless mode returns a dummy font (textureId 0).
+ *
+ * @returns The built-in BitmapFont (8x8 glyphs, 16 columns, 6 rows, ASCII 32-127).
  */
 export function getDefaultFont(): BitmapFont {
   if (defaultFont !== null) return defaultFont;
@@ -100,8 +127,12 @@ export function getDefaultFont(): BitmapFont {
 }
 
 /**
- * Measure the pixel dimensions of a text string.
- * Pure math — works in headless mode.
+ * Measure the pixel dimensions of a text string without drawing it.
+ * Pure math -- works in headless mode.
+ *
+ * @param text - The string to measure.
+ * @param options - Font and scale options. Default font and scale 1 if omitted.
+ * @returns Width and height in pixels.
  */
 export function measureText(
   text: string,
@@ -116,9 +147,24 @@ export function measureText(
 }
 
 /**
- * Draw a text string using the sprite pipeline.
- * Each character becomes one drawSprite() call.
- * No-op in headless mode.
+ * Draw a text string using the sprite pipeline (one sprite per character).
+ * Must be called every frame. No-op in headless mode.
+ *
+ * @param text - The string to draw.
+ * @param x - X position (screen pixels if screenSpace, world units otherwise).
+ * @param y - Y position (screen pixels if screenSpace, world units otherwise).
+ * @param options - Font, scale, tint, layer, and screenSpace options.
+ *
+ * @example
+ * // Draw HUD text at the top-left of the screen
+ * drawText("HP: 100", 10, 10, { scale: 2, screenSpace: true });
+ *
+ * @example
+ * // Draw world-space text above an entity
+ * drawText("Enemy", enemy.x, enemy.y - 12, {
+ *   tint: { r: 1, g: 0.3, b: 0.3, a: 1 },
+ *   layer: 50,
+ * });
  */
 export function drawText(
   text: string,

package/src/rendering/texture.ts

@@ -5,9 +5,16 @@ const hasRenderOps =
   typeof (globalThis as any).Deno?.core?.ops?.op_load_texture === "function";
 
 /**
- * Load a texture from a PNG file path. Returns a texture handle.
- * Caches by path — loading the same path twice returns the same handle.
+ * Load a texture from a PNG file path. Returns an opaque texture handle.
+ * Caches by path -- loading the same path twice returns the same handle.
  * Returns 0 (no texture) in headless mode.
+ *
+ * @param path - File path to a PNG image (relative to game entry file or absolute).
+ * @returns Texture handle for use with drawSprite(), createTilemap(), etc.
+ *
+ * @example
+ * const playerTex = loadTexture("assets/player.png");
+ * drawSprite({ textureId: playerTex, x: 0, y: 0, w: 32, h: 32 });
  */
 export function loadTexture(path: string): TextureId {
   if (!hasRenderOps) return 0;
@@ -15,9 +22,20 @@ export function loadTexture(path: string): TextureId {
 }
 
 /**
- * Create a solid-color 1x1 texture. Useful for placeholder sprites.
- * Colors are 0-255 RGBA.
+ * Create a 1x1 solid-color texture. Useful for rectangles, placeholder sprites,
+ * and UI elements. Cached by name -- creating the same name twice returns the same handle.
  * Returns 0 (no texture) in headless mode.
+ *
+ * @param name - Unique name for caching (e.g. "red", "health-green").
+ * @param r - Red channel, 0-255.
+ * @param g - Green channel, 0-255.
+ * @param b - Blue channel, 0-255.
+ * @param a - Alpha channel, 0-255. Default: 255 (fully opaque).
+ * @returns Texture handle for use with drawSprite().
+ *
+ * @example
+ * const redTex = createSolidTexture("red", 255, 0, 0);
+ * drawSprite({ textureId: redTex, x: 10, y: 10, w: 50, h: 50 });
  */
 export function createSolidTexture(
   name: string,

package/src/rendering/tilemap.ts

@@ -4,7 +4,14 @@ const hasRenderOps =
   typeof (globalThis as any).Deno !== "undefined" &&
   typeof (globalThis as any).Deno?.core?.ops?.op_create_tilemap === "function";
 
-/** Create a tilemap backed by a texture atlas. Returns a TilemapId handle. */
+/**
+ * Create a tilemap backed by a texture atlas. Returns an opaque TilemapId handle.
+ * The tilemap stores a grid of tile IDs that map to sub-regions of the atlas texture.
+ * Returns 0 in headless mode.
+ *
+ * @param opts - Tilemap configuration (atlas texture, grid size, tile size, atlas layout).
+ * @returns Tilemap handle for use with setTile(), getTile(), drawTilemap().
+ */
 export function createTilemap(opts: TilemapOptions): TilemapId {
   if (!hasRenderOps) return 0;
   return (globalThis as any).Deno.core.ops.op_create_tilemap(
@@ -17,7 +24,16 @@ export function createTilemap(opts: TilemapOptions): TilemapId {
   );
 }
 
-/** Set a tile at grid position (gx, gy). Tile ID 0 = empty. */
+/**
+ * Set a tile at grid position (gx, gy).
+ * Tile IDs correspond to positions in the texture atlas (left-to-right, top-to-bottom).
+ * Tile ID 0 = empty (not drawn). No-op in headless mode.
+ *
+ * @param id - Tilemap handle from createTilemap().
+ * @param gx - Grid X position (column). 0 = leftmost.
+ * @param gy - Grid Y position (row). 0 = topmost.
+ * @param tileId - Tile index in the atlas (1-based). 0 = empty/clear.
+ */
 export function setTile(
   id: TilemapId,
   gx: number,
@@ -28,13 +44,29 @@ export function setTile(
   (globalThis as any).Deno.core.ops.op_set_tile(id, gx, gy, tileId);
 }
 
-/** Get the tile ID at grid position (gx, gy). Returns 0 if out of bounds. */
+/**
+ * Get the tile ID at grid position (gx, gy).
+ * Returns 0 if out of bounds or in headless mode.
+ *
+ * @param id - Tilemap handle from createTilemap().
+ * @param gx - Grid X position (column).
+ * @param gy - Grid Y position (row).
+ * @returns Tile ID at the given position, or 0 if empty/out of bounds.
+ */
 export function getTile(id: TilemapId, gx: number, gy: number): number {
   if (!hasRenderOps) return 0;
   return (globalThis as any).Deno.core.ops.op_get_tile(id, gx, gy);
 }
 
-/** Draw all visible tiles as sprites (camera-culled). */
+/**
+ * Draw all visible tiles as sprites. Only draws tiles within the camera viewport (culled).
+ * Must be called every frame. No-op in headless mode.
+ *
+ * @param id - Tilemap handle from createTilemap().
+ * @param x - World X offset for the tilemap origin. Default: 0.
+ * @param y - World Y offset for the tilemap origin. Default: 0.
+ * @param layer - Draw order layer. Default: 0.
+ */
 export function drawTilemap(
   id: TilemapId,
   x: number = 0,

package/src/rendering/types.ts

@@ -1,54 +1,72 @@
-/** Opaque handle to a loaded texture. */
+/**
+ * Opaque handle to a loaded texture. Returned by {@link loadTexture} or {@link createSolidTexture}.
+ * A value of 0 means "no texture" (headless mode fallback).
+ */
 export type TextureId = number;
 
-/** Options for drawing a sprite. */
+/** Options for drawing a sprite via {@link drawSprite}. */
 export type SpriteOptions = {
   /** Texture handle from loadTexture() or createSolidTexture(). */
   textureId: TextureId;
-  /** World X position (top-left corner). */
+  /** World X position (top-left corner of sprite). */
   x: number;
-  /** World Y position (top-left corner). */
+  /** World Y position (top-left corner of sprite). */
   y: number;
-  /** Width in world units. */
+  /** Width in world units (pixels at zoom 1). */
   w: number;
-  /** Height in world units. */
+  /** Height in world units (pixels at zoom 1). */
   h: number;
-  /** Draw order layer (lower = drawn first / behind). Default: 0. */
+  /** Draw order layer. Lower values are drawn first (behind). Default: 0. Use 100+ for HUD elements. */
   layer?: number;
-  /** UV sub-rect for atlas sprites. Default: full texture. */
+  /**
+   * UV sub-rectangle for atlas/sprite-sheet textures.
+   * All values are normalized 0.0-1.0 (fraction of full texture).
+   * Default: full texture `{ x: 0, y: 0, w: 1, h: 1 }`.
+   */
   uv?: { x: number; y: number; w: number; h: number };
-  /** RGBA tint color (0-1 range). Default: white (1,1,1,1). */
+  /**
+   * RGBA tint color multiplied with the texture color.
+   * Each channel is 0.0-1.0. Default: white `{ r: 1, g: 1, b: 1, a: 1 }` (no tint).
+   */
   tint?: { r: number; g: number; b: number; a: number };
 };
 
-/** Camera state. */
+/** Camera state returned by {@link getCamera}. */
 export type CameraState = {
+  /** Camera center X position in world units. */
   x: number;
+  /** Camera center Y position in world units. */
   y: number;
+  /** Zoom level. 1.0 = default, >1.0 = zoomed in, <1.0 = zoomed out. */
   zoom: number;
 };
 
-/** Mouse position. */
+/** Mouse position in screen or world coordinates. */
 export type MousePosition = {
+  /** X position in pixels (screen) or world units (world). */
   x: number;
+  /** Y position in pixels (screen) or world units (world). */
   y: number;
 };
 
-/** Opaque handle to a tilemap. */
+/**
+ * Opaque handle to a tilemap. Returned by {@link createTilemap}.
+ * A value of 0 means "no tilemap" (headless mode fallback).
+ */
 export type TilemapId = number;
 
-/** Options for creating a tilemap. */
+/** Options for creating a tilemap via {@link createTilemap}. */
 export type TilemapOptions = {
-  /** Texture atlas handle from loadTexture(). */
+  /** Texture atlas handle from loadTexture(). Must be a valid TextureId. */
   textureId: number;
-  /** Grid width in tiles. */
+  /** Grid width in tiles. Must be a positive integer. */
   width: number;
-  /** Grid height in tiles. */
+  /** Grid height in tiles. Must be a positive integer. */
   height: number;
-  /** Size of each tile in world units. */
+  /** Size of each tile in world units (pixels at zoom 1). Must be positive. */
   tileSize: number;
-  /** Number of columns in the texture atlas. */
+  /** Number of tile columns in the texture atlas. Must be a positive integer. */
   atlasColumns: number;
-  /** Number of rows in the texture atlas. */
+  /** Number of tile rows in the texture atlas. Must be a positive integer. */
   atlasRows: number;
 };

package/src/rendering/validate.ts

@@ -1,10 +1,13 @@
 /**
- * Runtime validation for rendering API calls
- * Add this to production code to catch errors early
+ * Runtime validation for rendering API calls.
+ * Add validation to catch type errors and invalid values early in development.
  */
 
+/** Options controlling how validation errors are reported. */
 export interface ValidationOptions {
+  /** If true, throw on validation failure. Default: true. */
   throwOnError?: boolean;
+  /** If true, log errors to console.error. Default: false. */
   logErrors?: boolean;
 }
 
@@ -13,6 +16,15 @@ const defaultOptions: ValidationOptions = {
   logErrors: false,
 };
 
+/**
+ * Validate that a value is a finite number (not NaN, not Infinity).
+ *
+ * @param api - Name of the calling API (for error messages).
+ * @param param - Name of the parameter being validated.
+ * @param value - The value to validate.
+ * @param options - Error reporting options.
+ * @returns true if valid, false or throws if invalid.
+ */
 export function validateNumber(
   api: string,
   param: string,
@@ -37,6 +49,14 @@ export function validateNumber(
   return true;
 }
 
+/**
+ * Validate that a value is a valid Color object with r, g, b channels in 0.0-1.0.
+ *
+ * @param api - Name of the calling API (for error messages).
+ * @param color - The color object to validate.
+ * @param options - Error reporting options.
+ * @returns true if valid, false or throws if invalid.
+ */
 export function validateColor(
   api: string,
   color: any,
@@ -67,6 +87,13 @@ export function validateColor(
   return true;
 }
 
+/**
+ * Validate drawText options (x, y, size must be valid numbers, color must be valid).
+ *
+ * @param opts - The text options object to validate.
+ * @param options - Error reporting options.
+ * @returns true if valid, false or throws if invalid.
+ */
 export function validateTextOptions(
   opts: any,
   options: ValidationOptions = defaultOptions
@@ -87,6 +114,17 @@ export function validateTextOptions(
   return true;
 }
 
+/**
+ * Validate drawRect parameters (x, y, w, h must be finite numbers, color must be valid).
+ *
+ * @param x - X position to validate.
+ * @param y - Y position to validate.
+ * @param w - Width to validate.
+ * @param h - Height to validate.
+ * @param opts - Optional rect options with color.
+ * @param options - Error reporting options.
+ * @returns true if valid, false or throws if invalid.
+ */
 export function validateRectParams(
   x: any,
   y: any,
@@ -119,7 +157,14 @@ function handleError(message: string, options: ValidationOptions): boolean {
   return false;
 }
 
-// Helper: wrap a rendering function with validation
+/**
+ * Wrap a rendering function with automatic parameter validation.
+ * If validation fails, the wrapped function is not called.
+ *
+ * @param fn - The rendering function to wrap.
+ * @param validator - Validation function that receives the same args. Returns true if valid.
+ * @returns Wrapped function that validates before calling the original.
+ */
 export function withValidation<T extends (...args: any[]) => any>(
   fn: T,
   validator: (...args: Parameters<T>) => boolean

package/src/state/error.ts

@@ -1,4 +1,15 @@
-/** Structured error type — per docs/api-design.md */
+/**
+ * Structured error type for the Arcane engine.
+ * Provides machine-readable codes, human-readable messages, and actionable context.
+ * Follows the error design in docs/api-design.md.
+ *
+ * - `code` - Machine-readable error code (e.g., "TRANSACTION_FAILED", "INVALID_PATH").
+ * - `message` - Human-readable error description.
+ * - `context.action` - What operation was being attempted.
+ * - `context.reason` - Why the operation failed.
+ * - `context.state` - Optional snapshot of relevant state at failure time.
+ * - `context.suggestion` - Optional suggestion for how to fix the error.
+ */
 export type ArcaneError = Readonly<{
   code: string;
   message: string;
@@ -10,7 +21,15 @@ export type ArcaneError = Readonly<{
   }>;
 }>;
 
-/** Create an ArcaneError */
+/**
+ * Create an ArcaneError with structured context.
+ * Pure function — returns a new frozen error object.
+ *
+ * @param code - Machine-readable error code (e.g., "TRANSACTION_FAILED").
+ * @param message - Human-readable error description.
+ * @param context - Structured context with action, reason, and optional suggestion.
+ * @returns A new ArcaneError object.
+ */
 export function createError(
   code: string,
   message: string,

package/src/state/observe.ts

@@ -1,36 +1,62 @@
 import type { Diff } from "./transaction.ts";
 
-/** Observer callback — receives new value, old value, and context */
+/**
+ * Callback invoked when an observed path changes.
+ * Receives the new value, old value, and context about the change.
+ *
+ * @param newValue - The value after the change.
+ * @param oldValue - The value before the change.
+ * @param context - Metadata about the change (path, full diff).
+ */
 export type ObserverCallback<T = unknown> = (
   newValue: T,
   oldValue: T,
   context: ObserverContext,
 ) => void;
 
-/** Context provided to observer callbacks */
+/**
+ * Context provided to observer callbacks when a change is detected.
+ *
+ * - `path` - The specific path that changed (e.g., "player.hp").
+ * - `diff` - The full Diff from the transaction that triggered this notification.
+ */
 export type ObserverContext = Readonly<{
   path: string;
   diff: Diff;
 }>;
 
-/** Unsubscribe function */
+/**
+ * Function returned by observe() to unsubscribe from further notifications.
+ * Call it to stop receiving callbacks for that subscription.
+ */
 export type Unsubscribe = () => void;
 
-/** Pattern for path matching (supports * wildcards) */
+/**
+ * Pattern for matching state paths. Supports `*` wildcards at any segment position.
+ * Examples: "player.hp", "enemies.*.hp", "*.position".
+ * Each `*` matches exactly one path segment.
+ */
 export type PathPattern = string;
 
-/** Observer registry — manages subscriptions and dispatches notifications */
+/**
+ * Observer registry that manages subscriptions and dispatches change notifications.
+ * Created via {@link createObserverRegistry}. Used internally by GameStore.
+ *
+ * - `observe` - Subscribe to changes matching a path pattern. Returns an Unsubscribe function.
+ * - `notify` - Dispatch notifications to all matching observers for a given diff.
+ * - `clear` - Remove all observers (useful for cleanup/reset).
+ */
 export type ObserverRegistry<S> = Readonly<{
-  /** Subscribe to changes at a path pattern */
+  /** Subscribe to changes at a path pattern. Returns an unsubscribe function. */
   observe: <T = unknown>(
     pattern: PathPattern,
     callback: ObserverCallback<T>,
   ) => Unsubscribe;
 
-  /** Notify all matching observers after a transaction commits */
+  /** Notify all matching observers after a transaction commits. */
   notify: (oldState: S, newState: S, diff: Diff) => void;
 
-  /** Remove all observers */
+  /** Remove all observers. */
   clear: () => void;
 }>;
 
@@ -39,7 +65,12 @@ type Subscription = {
   callback: ObserverCallback;
 };
 
-/** Create a new observer registry */
+/**
+ * Create a new observer registry for tracking state change subscriptions.
+ * Used internally by {@link createStore} to power the store's observe() method.
+ *
+ * @returns A new ObserverRegistry with observe, notify, and clear methods.
+ */
 export function createObserverRegistry<S>(): ObserverRegistry<S> {
   const subscriptions = new Set<Subscription>();
 

package/src/state/prng.ts

@@ -1,4 +1,13 @@
-/** Opaque PRNG state — serializable, deterministic (xoshiro128**) */
+/**
+ * Opaque PRNG state using the xoshiro128** algorithm.
+ * Serializable and deterministic — the same seed always produces the same sequence.
+ * All PRNG functions are pure: they take a PRNGState and return a new PRNGState.
+ * Create via {@link seed}.
+ *
+ * - `__brand` - Type brand, always "PRNGState".
+ * - `seed` - The original seed value used to initialize this state.
+ * - `s0`, `s1`, `s2`, `s3` - Internal 32-bit state words. Do not modify directly.
+ */
 export type PRNGState = Readonly<{
   readonly __brand: "PRNGState";
   seed: number;
@@ -8,7 +17,18 @@ export type PRNGState = Readonly<{
   s3: number;
 }>;
 
-/** Create a seeded PRNG */
+/**
+ * Create a seeded PRNG state. The same seed always produces the same random sequence.
+ * Uses splitmix32 to initialize the xoshiro128** internal state.
+ *
+ * @param n - The seed value. Truncated to a 32-bit integer.
+ * @returns A new PRNGState ready for use with {@link rollDice}, {@link randomInt}, etc.
+ *
+ * @example
+ * const rng = seed(42);
+ * const [value, rng2] = randomInt(rng, 1, 6);
+ * // value is deterministic for seed 42
+ */
 export function seed(n: number): PRNGState {
   // Initialize state from seed using splitmix32
   let s = n | 0;
@@ -30,17 +50,33 @@ export function seed(n: number): PRNGState {
   };
 }
 
-/** Dice notation: "2d6+3" */
+/**
+ * Branded string type for dice notation (e.g., "2d6+3", "1d20", "3d8-1").
+ * Format: `NdS` or `NdS+M` / `NdS-M` where N=count, S=sides, M=modifier.
+ */
 export type DiceNotation = string & { readonly __dice: true };
 
-/** Parsed dice specification */
+/**
+ * Parsed dice specification. Created by {@link parseDice} or passed directly to {@link rollDice}.
+ *
+ * - `count` - Number of dice to roll (the N in NdS). Must be >= 1.
+ * - `sides` - Number of sides per die (the S in NdS). Must be >= 1.
+ * - `modifier` - Added to the total after all dice are summed. Can be negative.
+ */
 export type DiceSpec = Readonly<{
   count: number;
   sides: number;
   modifier: number;
 }>;
 
-/** Parse dice notation string into a spec */
+/**
+ * Parse a dice notation string into a DiceSpec.
+ * Pure function. Throws if the notation is invalid.
+ *
+ * @param notation - Dice notation string (e.g., "2d6+3", "1d20", "3d8-1").
+ * @returns Parsed DiceSpec with count, sides, and modifier.
+ * @throws Error if notation doesn't match the `NdS` or `NdS+M` / `NdS-M` format.
+ */
 export function parseDice(notation: string): DiceSpec {
   const match = notation.match(/^(\d+)d(\d+)([+-]\d+)?$/);
   if (!match) {
@@ -55,7 +91,22 @@ export function parseDice(notation: string): DiceSpec {
   };
 }
 
-/** Roll dice. Returns [result, newRngState] */
+/**
+ * Roll dice deterministically using the PRNG. Pure function — returns the result
+ * and a new PRNGState without modifying the original.
+ *
+ * Accepts either a DiceSpec object or a dice notation string (e.g., "2d6+3").
+ * Each die is rolled individually using {@link randomInt}, then summed with the modifier.
+ *
+ * @param rng - Current PRNG state.
+ * @param spec - A DiceSpec or dice notation string (e.g., "1d20", "2d6+3").
+ * @returns A tuple of [total roll result, new PRNGState].
+ *
+ * @example
+ * const rng = seed(42);
+ * const [damage, rng2] = rollDice(rng, "2d6+3");
+ * const [toHit, rng3] = rollDice(rng2, "1d20");
+ */
 export function rollDice(
   rng: PRNGState,
   spec: DiceSpec | string,
@@ -73,7 +124,15 @@ export function rollDice(
   return [total, current];
 }
 
-/** Random integer in [min, max] inclusive */
+/**
+ * Generate a random integer in the range [min, max] (inclusive on both ends).
+ * Pure function — returns the value and a new PRNGState.
+ *
+ * @param rng - Current PRNG state.
+ * @param min - Minimum value (inclusive).
+ * @param max - Maximum value (inclusive). Must be >= min.
+ * @returns A tuple of [random integer, new PRNGState].
+ */
 export function randomInt(
   rng: PRNGState,
   min: number,
@@ -85,14 +144,26 @@ export function randomInt(
   return [value, next];
 }
 
-/** Random float in [0, 1) */
+/**
+ * Generate a random float in the range [0, 1) (inclusive of 0, exclusive of 1).
+ * Pure function — returns the value and a new PRNGState.
+ *
+ * @param rng - Current PRNG state.
+ * @returns A tuple of [random float in [0,1), new PRNGState].
+ */
 export function randomFloat(rng: PRNGState): [number, PRNGState] {
   const next = advance(rng);
   const result = (xoshiro128ss(rng) >>> 0) / 4294967296;
   return [result, next];
 }
 
-/** Pick one random element */
+/**
+ * Pick one random element from an array. Pure function — does not modify the array.
+ *
+ * @param rng - Current PRNG state.
+ * @param items - Non-empty array to pick from.
+ * @returns A tuple of [randomly selected item, new PRNGState].
+ */
 export function randomPick<T>(
   rng: PRNGState,
   items: readonly T[],
@@ -101,7 +172,14 @@ export function randomPick<T>(
   return [items[index], next];
 }
 
-/** Shuffle array (Fisher-Yates). Returns new array. */
+/**
+ * Shuffle an array using Fisher-Yates algorithm. Pure function — returns a new
+ * shuffled array without modifying the original.
+ *
+ * @param rng - Current PRNG state.
+ * @param items - Array to shuffle.
+ * @returns A tuple of [new shuffled array, new PRNGState].
+ */
 export function shuffle<T>(
   rng: PRNGState,
   items: readonly T[],