Add stdlib Random API and migrate tetris RNG

docs/ai_stdlib_reference.md

@@ -20,6 +20,7 @@ Sources: `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt`, `lynglib/s
 - Values: `Unset`, `π`.
 - Primitive/class symbols: `Object`, `Int`, `Real`, `Bool`, `Char`, `String`, `Class`, `Callable`.
 - Collections/types: `Iterable`, `Iterator`, `Collection`, `Array`, `List`, `ImmutableList`, `Set`, `ImmutableSet`, `Map`, `ImmutableMap`, `MapEntry`, `Range`, `RingBuffer`.
+- Random: singleton `Random` and class `SeededRandom`.
 - Async types: `Deferred`, `CompletableDeferred`, `Mutex`, `Flow`, `FlowBuilder`.
 - Delegation types: `Delegate`, `DelegateContext`.
 - Regex types: `Regex`, `RegexMatch`.
@@ -30,6 +31,7 @@ Sources: `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt`, `lynglib/s
 - Exceptions/delegation base: `Exception`, `IllegalArgumentException`, `NotImplementedException`, `Delegate`.
 - Collections and iterables: `Iterable<T>`, `Iterator<T>`, `Collection<T>`, `Array<T>`, `List<T>`, `ImmutableList<T>`, `Set<T>`, `ImmutableSet<T>`, `Map<K,V>`, `ImmutableMap<K,V>`, `MapEntry<K,V>`, `RingBuffer<T>`.
 - Host iterator bridge: `KotlinIterator<T>`.
+- Random APIs: `extern object Random`, `extern class SeededRandom`.
 
 ### 4.2 High-use extension APIs
 - Iteration/filtering: `forEach`, `filter`, `filterFlow`, `filterNotNull`, `filterFlowNotNull`, `drop`, `dropLast`, `takeLast`.
@@ -48,6 +50,8 @@ Sources: `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt`, `lynglib/s
 - `$~` (last regex match object).
 - `TODO(message?)` utility.
 - `StackTraceEntry` class.
+- `Random.nextInt()`, `Random.nextFloat()`, `Random.next(range)`, `Random.seeded(seed)`.
+- `SeededRandom.nextInt()`, `SeededRandom.nextFloat()`, `SeededRandom.next(range)`.
 
 ## 5. Additional Built-in Modules (import explicitly)
 - `import lyng.observable`

docs/math.md

@@ -110,6 +110,29 @@ For example:
     assert( 5.clamp(0..10) == 5 )
     >>> void
 
+## Random values
+
+Lyng stdlib provides a global random singleton and deterministic seeded generators:
+
+| name                     | meaning |
+|--------------------------|---------|
+| Random.nextInt()         | random `Int` from full platform range |
+| Random.nextFloat()       | random `Real` in `[0,1)` |
+| Random.next(range)       | random value from the given finite range |
+| Random.seeded(seed)      | creates deterministic generator |
+| SeededRandom.nextInt()   | deterministic random `Int` |
+| SeededRandom.nextFloat() | deterministic random `Real` in `[0,1)` |
+| SeededRandom.next(range) | deterministic random value from range |
+
+Examples:
+
+    val rng = Random.seeded(1234)
+    assert( rng.next(1..10) in 1..10 )
+    assert( rng.next('a'..<'f') in 'a'..<'f' )
+    assert( rng.next(0.0..<1.0) >= 0.0 )
+    assert( rng.next(0.0..<1.0) < 1.0 )
+    >>> void
+
 ## Scientific constant
 
 | name                 | meaning      |