AGENTS.md

@@ -5,14 +5,6 @@
 - For generics-heavy code generation, follow `docs/ai_language_reference.md` section `7.1 Generics Runtime Model and Bounds` and `7.2 Differences vs Java / Kotlin / Scala`.
 - Use `docs/ai_stdlib_reference.md` for default runtime/module APIs and stdlib surface.
 - Treat `LYNG_AI_SPEC.md` and older docs as secondary if they conflict with the two files above.
-- Prefer the shortest clear loop: use `for` for straightforward iteration/ranges; use `while` only when loop state/condition is irregular or changes in ways `for` cannot express cleanly.
-- In Lyng code, slice strings with range indexing (`text[a..<b]`, `text[..<n]`, `text[n..]`) and avoid Java/Kotlin-style `substring(...)`.
-
-## Lyng-First API Declarations
-- Use `.lyng` declarations as the single source of truth for Lyng-facing API docs and types (especially module extern declarations).
-- Prefer defining Lyng entities (enums/classes/type shapes) in `.lyng` files; only define them in Kotlin when there is Kotlin/platform-specific implementation detail that cannot be expressed in Lyng.
-- Avoid hardcoding Lyng API documentation in Kotlin registrars when it can be declared in `.lyng`; Kotlin-side docs should be fallback/bridge only.
-- For mixed pluggable modules (Lyng + Kotlin), embed module `.lyng` sources as generated Kotlin string literals, evaluate them into module scope during registration, then attach Kotlin implementations/bindings.
 
 ## Kotlin/Wasm generation guardrails
 - Avoid creating suspend lambdas for compiler runtime statements. Prefer explicit `object : Statement()` with `override suspend fun execute(...)`.

docs/lyng.io.console.md

@@ -40,18 +40,7 @@ Console.setCursorVisible(true)
 Console.flush()
 ```
 
-#### Tetris sample
-
-The repository includes a full interactive Tetris sample that demonstrates:
-
-- alternate screen rendering
-- raw keyboard input
-- resize handling
-- typed console events
-
-![Lyng Tetris sample](/tetris.png)
-
-Run it from the project root in a real TTY:
+Interactive sample script in this repo:
 
 ```bash
 lyng examples/tetris_console.lyng
@@ -61,7 +50,7 @@ lyng examples/tetris_console.lyng
 
 - `Console.isSupported(): Bool` — whether console control is available on this platform/runtime.
 - `Console.isTty(): Bool` — whether output is attached to a TTY.
-- `Console.ansiLevel(): ConsoleAnsiLevel` — `NONE`, `BASIC16`, `ANSI256`, `TRUECOLOR`.
+- `Console.ansiLevel(): String` — `NONE`, `BASIC16`, `ANSI256`, `TRUECOLOR`.
 - `Console.geometry(): ConsoleGeometry?` — `{columns, rows}` as typed object or `null`.
 - `Console.details(): ConsoleDetails` — consolidated capability object.
 - `Console.write(text: String)` — writes to console output.
@@ -92,9 +81,9 @@ launch {
 
 #### Event format
 
-`Console.events()` emits `ConsoleEvent` with:
+`Console.events()` emits `ConsoleEvent` with at least:
 
-- `type: ConsoleEventType` — `UNKNOWN`, `RESIZE`, `KEY_DOWN`, `KEY_UP`
+- `type: String` — `resize`, `keydown`, `keyup`
 
 Additional fields:
 

examples/tetris_console.lyng

@@ -8,25 +8,15 @@
  *  - Up arrow or W: rotate
  *  - Down arrow or S: soft drop
  *  - Space: hard drop
- *  - P or Escape: pause
- *  - Q: quit
-
-    Tsted to score:
-sergeych@sergeych-XPS-17-9720:~$ ~/dev/lyng/examples/tetris_console.lyng
-Bye.
-Score: 435480
-Lines: 271
-Level: 28
-Ssergeych@sergeych-XPS-17-9720:~$
+ *  - Q or Escape: quit
  */
 
 import lyng.io.console
-import lyng.io.fs
 
 val MIN_COLS = 56
 val MIN_ROWS = 24
 val PANEL_WIDTH = 24
-val BOARD_MARGIN_ROWS = 5
+val BOARD_MARGIN_ROWS = 8
 val BOARD_MIN_W = 10
 val BOARD_MAX_W = 16
 val BOARD_MIN_H = 16
@@ -36,11 +26,9 @@ val DROP_FRAMES_BASE = 15
 val DROP_FRAMES_MIN = 3
 val FRAME_DELAY_MS = 35
 val RESIZE_WAIT_MS = 250
-val MAX_PENDING_INPUTS = 64
 val ROTATION_KICKS = [0, -1, 1, -2, 2]
 val ANSI_ESC = "\u001b["
 val ANSI_RESET = ANSI_ESC + "0m"
-val ERROR_LOG_PATH = "/tmp/lyng_tetris_errors.log"
 val UNICODE_BLOCK = "██"
 val UNICODE_TOP_LEFT = "┌"
 val UNICODE_TOP_RIGHT = "┐"
@@ -76,7 +64,6 @@ class GameState(
     var level = 1
     var running = true
     var gameOver = false
-    var paused = false
 }
 class LoopFrame(val resized: Bool, val originRow: Int, val originCol: Int) {}
 
@@ -85,44 +72,44 @@ fun clearAndHome() {
     Console.home()
 }
 
-fun logError(message: String, err: Object?): Void {
-    try {
-        var details = ""
-        if (err != null) {
-            try {
-                details = ": " + err
-            } catch (_: Object) {
-                details = ": <error-format-failed>"
-            }
-        }
-        Path(ERROR_LOG_PATH).appendUtf8(message + details + "\n")
-    } catch (_: Object) {
-        // Never let logging errors affect gameplay.
-    }
-}
-
 fun repeatText(s: String, n: Int): String {
     var out: String = ""
-    for (i in 0..<n) {
+    var i = 0
+    while (i < n) {
         out += s
+        i = i + 1
     }
     out
 }
 
-fun max<T>(a: T, b: T): T = if (a > b) a else b
+fun maxInt(a: Int, b: Int): Int {
+    if (a > b) a else b
+}
+
+fun minInt(a: Int, b: Int): Int {
+    if (a < b) a else b
+}
+
+fun clampInt(v: Int, lo: Int, hi: Int): Int {
+    minInt(hi, maxInt(lo, v))
+}
 
 fun emptyRow(width: Int): Row {
     val r: Row = []
-    for (x in 0..<width) {
+    var x = 0
+    while (x < width) {
         r.add(0)
+        x = x + 1
     }
     r
 }
 
 fun createBoard(width: Int, height: Int): Board {
     val b: Board = []
-    for (y in 0..<height) {
+    var y = 0
+    while (y < height) {
         b.add(emptyRow(width))
+        y = y + 1
     }
     b
 }
@@ -152,30 +139,22 @@ fun emptyCellText(useColor: Bool): String {
 }
 
 fun canPlace(board: Board, boardW: Int, boardH: Int, pieceId: Int, rot: Int, px: Int, py: Int): Bool {
-    try {
-        if (pieceId < 1 || pieceId > 7) return false
-        val piece: Piece = PIECES[pieceId - 1]
-        if (rot < 0 || rot >= piece.rotations.size) return false
-        val cells = piece.rotations[rot]
+    val piece: Piece = PIECES[pieceId - 1]
+    val cells = piece.rotations[rot]
 
-        for (cell in cells) {
-            val x = px + cell[0]
-            val y = py + cell[1]
+    for (cell in cells) {
+        val x = px + cell[0]
+        val y = py + cell[1]
 
-            if (x < 0 || x >= boardW) return false
-            if (y >= boardH) return false
+        if (x < 0 || x >= boardW) return false
+        if (y >= boardH) return false
 
-            if (y >= 0) {
-                if (y >= board.size) return false
-                val row = board[y]
-                if (row == null) return false
-                if (row[x] != 0) return false
-            }
+        if (y >= 0) {
+            val row = board[y]
+            if (row[x] != 0) return false
         }
-        true
-    } catch (_: Object) {
-        false
     }
+    true
 }
 
 fun lockPiece(board: Board, pieceId: Int, rot: Int, px: Int, py: Int): Void {
@@ -186,11 +165,9 @@ fun lockPiece(board: Board, pieceId: Int, rot: Int, px: Int, py: Int): Void {
         val x = px + cell[0]
         val y = py + cell[1]
 
-        if (y >= 0 && y < board.size) {
+        if (y >= 0) {
             val row = board[y]
-            if (row != null) {
-                row[x] = pieceId
-            }
+            row[x] = pieceId
         }
     }
 }
@@ -201,31 +178,23 @@ fun clearCompletedLines(board: Board, boardW: Int, boardH: Int): Int {
     var cleared = 0
 
     while (y >= 0) {
-        if (y >= b.size) {
-            y--
-            continue
-        }
         val row = b[y]
-        if (row == null) {
-            b.removeAt(y)
-            b.insertAt(0, emptyRow(boardW))
-            cleared++
-            continue
-        }
         var full = true
-        for (x in 0..<boardW) {
+        var x = 0
+        while (x < boardW) {
             if (row[x] == 0) {
                 full = false
                 break
             }
+            x = x + 1
         }
 
         if (full) {
             b.removeAt(y)
             b.insertAt(0, emptyRow(boardW))
-            cleared++
+            cleared = cleared + 1
         } else {
-            y--
+            y = y - 1
         }
     }
 
@@ -251,7 +220,7 @@ fun tryRotateCw(board: Board, boardW: Int, boardH: Int, pieceId: Int, rot: Int,
     val nr = (rot + 1) % rotations
     for (kx in ROTATION_KICKS) {
         val nx = px + kx
-        if (canPlace(board, boardW, boardH, pieceId, nr, nx, py) == true) {
+        if (canPlace(board, boardW, boardH, pieceId, nr, nx, py)) {
             return RotateResult(true, nr, nx)
         }
     }
@@ -261,18 +230,21 @@ fun tryRotateCw(board: Board, boardW: Int, boardH: Int, pieceId: Int, rot: Int,
 fun nextPreviewLines(pieceId: Int, useColor: Bool): List<String> {
     val out: List<String> = []
     if (pieceId <= 0) {
-        for (i in 0..<4) {
-            out.add("        ")
-        }
+        out.add("        ")
+        out.add("        ")
+        out.add("        ")
+        out.add("        ")
         return out
     }
 
     val piece: Piece = PIECES[pieceId - 1]
     val cells = piece.rotations[0]
 
-    for (y in 0..<4) {
+    var y = 0
+    while (y < 4) {
         var line = ""
-        for (x in 0..<4) {
+        var x = 0
+        while (x < 4) {
             var filled = false
             for (cell in cells) {
                 if (cell[0] == x && cell[1] == y) {
@@ -281,8 +253,10 @@ fun nextPreviewLines(pieceId: Int, useColor: Bool): List<String> {
                 }
             }
             line += if (filled) blockText(pieceId, useColor) else "  "
+            x = x + 1
         }
         out.add(line)
+        y = y + 1
     }
     out
 }
@@ -322,101 +296,52 @@ fun render(
     panel.add("W/Up: rotate")
     panel.add("S/Down: drop")
     panel.add("Space: hard drop")
-    panel.add("P/Esc: pause")
-    panel.add("Q: quit")
+    panel.add("Q/Esc: quit")
 
     val frameLines: List<String> = []
 
-    for (y in 0..<boardH) {
+    var y = 0
+    while (y < boardH) {
         var line = UNICODE_VERTICAL
 
-        for (x in 0..<boardW) {
+        var x = 0
+        while (x < boardW) {
             val a = activeCellId(state.pieceId, state.rot, state.px, state.py, x, y)
-            val row = if (y < board.size) board[y] else null
-            val b = if (row == null) 0 else row[x]
+            val row = board[y]
+            val b = row[x]
             val id = if (a > 0) a else b
             line += if (id > 0) blockText(id, useColor) else emptyCellText(useColor)
+            x = x + 1
         }
 
         line += UNICODE_VERTICAL
 
-        if (y < panel.size) {
-            line += "   " + panel[y]
+        val p = y
+        if (p < panel.size) {
+            line += "   " + panel[p]
         }
 
         frameLines.add(line)
+        y = y + 1
     }
 
     frameLines.add(bottomBorder)
 
-    for (i in 0..<frameLines.size) {
+    val prev = prevFrameLines
+    var i = 0
+    while (i < frameLines.size) {
         val line = frameLines[i]
-        val old = if (i < prevFrameLines.size) prevFrameLines[i] else null
+        val old = if (i < prev.size) prev[i] else null
         if (old != line) {
             Console.moveTo(originRow + i, originCol)
             Console.clearLine()
             Console.write(line)
         }
+        i = i + 1
     }
     frameLines
 }
 
-fun fitLine(line: String, width: Int): String {
-    val maxLen = if (width > 0) width else 0
-    if (maxLen <= 0) return ""
-    if (line.size >= maxLen) return line[..<maxLen]
-    line + repeatText(" ", maxLen - line.size)
-}
-
-fun renderPauseOverlay(
-    originRow: Int,
-    originCol: Int,
-    boardW: Int,
-    boardH: Int,
-): Void {
-    val contentWidth = boardW * 2 + 2 + 3 + PANEL_WIDTH
-    val contentHeight = boardH + 1
-
-    val lines: List<String> = []
-    lines.add("PAUSED")
-    lines.add("")
-    lines.add("Any key: continue game")
-    lines.add("Esc: exit game")
-    lines.add("")
-    lines.add("Move: A/D or arrows")
-    lines.add("Rotate: W or Up")
-    lines.add("Drop: S/Down, Space hard drop")
-
-    var innerWidth = 0
-    for (line in lines) {
-        if (line.size > innerWidth) innerWidth = line.size
-    }
-    innerWidth += 4
-    val maxInner = max(12, contentWidth - 2)
-    if (innerWidth > maxInner) innerWidth = maxInner
-    if (innerWidth % 2 != 0) innerWidth--
-
-    val boxWidth = innerWidth + 2
-    val boxHeight = lines.size + 2
-
-    val left = originCol + max(0, (contentWidth - boxWidth) / 2)
-    val top = originRow + max(0, (contentHeight - boxHeight) / 2)
-
-    val topBorder = UNICODE_TOP_LEFT + repeatText(UNICODE_HORIZONTAL, innerWidth / 2) + UNICODE_TOP_RIGHT
-    val bottomBorder = UNICODE_BOTTOM_LEFT + repeatText(UNICODE_HORIZONTAL, innerWidth / 2) + UNICODE_BOTTOM_RIGHT
-
-    Console.moveTo(top, left)
-    Console.write(topBorder)
-
-    for (i in 0..<lines.size) {
-        Console.moveTo(top + 1 + i, left)
-        Console.write(UNICODE_VERTICAL + fitLine("  " + lines[i], innerWidth) + UNICODE_VERTICAL)
-    }
-
-    Console.moveTo(top + boxHeight - 1, left)
-    Console.write(bottomBorder)
-}
-
 fun waitForMinimumSize(minCols: Int, minRows: Int): Object {
     while (true) {
         val g = Console.geometry()
@@ -426,23 +351,9 @@ fun waitForMinimumSize(minCols: Int, minRows: Int): Object {
         if (cols >= minCols && rows >= minRows) return g
 
         clearAndHome()
-        val lines: List<String> = []
-        lines.add("Lyng Tetris needs at least %sx%s terminal size."(minCols, minRows))
-        lines.add("Current: %sx%s"(cols, rows))
-        lines.add("Resize the console window to continue.")
-
-        val visibleLines = if (rows < lines.size) rows else lines.size
-        if (visibleLines > 0) {
-            val startRow = max(1, ((rows - visibleLines) / 2) + 1)
-            for (i in 0..<visibleLines) {
-                val line = lines[i]
-                val startCol = max(1, ((cols - line.size) / 2) + 1)
-                Console.moveTo(startRow + i, startCol)
-                Console.clearLine()
-                Console.write(line)
-            }
-            Console.flush()
-        }
+        println("Lyng Tetris needs at least %sx%s terminal size."(minCols, minRows))
+        println("Current: %sx%s"(cols, rows))
+        println("Resize the console window to continue...")
         delay(RESIZE_WAIT_MS)
     }
 }
@@ -523,8 +434,8 @@ if (!Console.isSupported()) {
     val cols = g0?.columns ?: MIN_COLS
     val rows = g0?.rows ?: MIN_ROWS
 
-    val boardW = clamp((cols - PANEL_WIDTH) / 2, BOARD_MIN_W..BOARD_MAX_W)
-    val boardH = clamp(rows - BOARD_MARGIN_ROWS, BOARD_MIN_H..BOARD_MAX_H)
+    val boardW = clampInt((cols - PANEL_WIDTH) / 2, BOARD_MIN_W, BOARD_MAX_W)
+    val boardH = clampInt(rows - BOARD_MARGIN_ROWS, BOARD_MIN_H, BOARD_MAX_H)
 
     val board: Board = createBoard(boardW, boardH)
 
@@ -541,9 +452,8 @@ if (!Console.isSupported()) {
     )
     var prevFrameLines: List<String> = []
 
-    val gameMutex: Mutex = Mutex()
-    var forceRedraw = false
-    val pendingInputs: List<String> = []
+    val gameMutex = Mutex()
+    var hasResizeEvent = false
 
     val rawModeEnabled = Console.setRawMode(true)
     if (!rawModeEnabled) {
@@ -551,66 +461,39 @@ if (!Console.isSupported()) {
         println("Use jlyng in an interactive terminal with raw input support.")
         void
     } else {
-        val useColor = Console.ansiLevel() != ConsoleAnsiLevel.NONE
+        val useColor = Console.ansiLevel() != "NONE"
         Console.enterAltScreen()
         Console.setCursorVisible(false)
         clearAndHome()
 
-        fun resetActivePiece(s: GameState): Void {
-            s.pieceId = nextPieceId()
-            s.rot = 0
-            s.px = (boardW / 2) - 2
-            s.py = -1
-        }
-
         fun applyKeyInput(s: GameState, key: String): Void {
-            try {
-                if (key == "__CTRL_C__") {
-                    s.running = false
+            if (key == "__CTRL_C__" || key == "q" || key == "Q" || key == "Escape") {
+                s.running = false
+            }
+            else if (key == "ArrowLeft" || key == "a" || key == "A") {
+                if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px - 1, s.py)) s.px = s.px - 1
+            }
+            else if (key == "ArrowRight" || key == "d" || key == "D") {
+                if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px + 1, s.py)) s.px = s.px + 1
+            }
+            else if (key == "ArrowUp" || key == "w" || key == "W") {
+                val rr: RotateResult = tryRotateCw(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py)
+                if (rr.ok) {
+                    s.rot = rr.rot
+                    s.px = rr.px
                 }
-                else if (s.paused) {
-                    if (key == "Escape") {
-                        s.running = false
-                    } else {
-                        s.paused = false
-                        forceRedraw = true
-                    }
+            }
+            else if (key == "ArrowDown" || key == "s" || key == "S") {
+                if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py + 1)) {
+                    s.py = s.py + 1
+                    s.score = s.score + 1
                 }
-                else if (key == "p" || key == "P" || key == "Escape") {
-                    s.paused = true
-                    forceRedraw = true
+            }
+            else if (key == " ") {
+                while (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py + 1)) {
+                    s.py = s.py + 1
+                    s.score = s.score + 2
                 }
-                else if (key == "q" || key == "Q") {
-                    s.running = false
-                }
-                else if (key == "ArrowLeft" || key == "a" || key == "A") {
-                    if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px - 1, s.py) == true) s.px--
-                }
-                else if (key == "ArrowRight" || key == "d" || key == "D") {
-                    if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px + 1, s.py) == true) s.px++
-                }
-                else if (key == "ArrowUp" || key == "w" || key == "W") {
-                    val rr: RotateResult = tryRotateCw(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py)
-                    if (rr.ok) {
-                        s.rot = rr.rot
-                        s.px = rr.px
-                    }
-                }
-                else if (key == "ArrowDown" || key == "s" || key == "S") {
-                    if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py + 1) == true) {
-                        s.py++
-                        s.score++
-                    }
-                }
-                else if (key == " ") {
-                    while (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py + 1) == true) {
-                        s.py++
-                        s.score += 2
-                    }
-                }
-            } catch (inputErr: Object) {
-                logError("applyKeyInput recovered after error", inputErr)
-                resetActivePiece(s)
             }
         }
 
@@ -620,47 +503,26 @@ if (!Console.isSupported()) {
                 try {
                     for (ev in Console.events()) {
                         if (!inputRunning) break
-
-                        // Isolate per-event failures so one bad event does not unwind the stream.
-                        try {
-                            if (ev is ConsoleKeyEvent) {
-                                val ke = ev as ConsoleKeyEvent
-                                if (ke.type == ConsoleEventType.KEY_DOWN) {
-                                    var key = ""
-                                    var ctrl = false
-                                    try {
-                                        key = ke.key
-                                    } catch (keyErr: Object) {
-                                        logError("Input key read error", keyErr)
-                                    }
-                                    try {
-                                        ctrl = ke.ctrl == true
-                                    } catch (_: Object) {
-                                        ctrl = false
-                                    }
-                                    if (key == "") {
-                                        logError("Dropped key event with empty/null key", null)
-                                        continue
-                                    }
+                        if (ev is ConsoleKeyEvent) {
+                            val ke = ev as ConsoleKeyEvent
+                            if (ke.type == "keydown") {
+                                val key = ke.key
+                                val ctrl = ke.ctrl
+                                gameMutex.withLock {
                                     val mapped = if (ctrl && (key == "c" || key == "C")) "__CTRL_C__" else key
-                                    val mm: Mutex = gameMutex
-                                    mm.withLock {
-                                        if (pendingInputs.size >= MAX_PENDING_INPUTS) {
-                                            pendingInputs.removeAt(0)
-                                        }
-                                        pendingInputs.add(mapped)
-                                    }
+                                    applyKeyInput(state, mapped)
                                 }
                             }
-                        } catch (eventErr: Object) {
-                            // Keep the input stream alive; report for diagnostics.
-                            logError("Input event error", eventErr)
+                        } else if (ev is ConsoleResizeEvent) {
+                            gameMutex.withLock {
+                                hasResizeEvent = true
+                                prevFrameLines = []
+                            }
                         }
                     }
-                } catch (err: Object) {
-                    // Recover stream-level failures by recreating event stream in next loop turn.
+                } catch (err: Exception) {
+                    // Keep game alive: transient console-event failures should not force quit.
                     if (!inputRunning) break
-                    logError("Input stream recovered after error", err)
                     Console.setRawMode(true)
                     delay(50)
                 }
@@ -678,10 +540,16 @@ if (!Console.isSupported()) {
                 return null
             }
 
+            var resized = false
+            gameMutex.withLock {
+                resized = hasResizeEvent
+                hasResizeEvent = false
+            }
+
             val contentCols = boardW * 2 + 2 + 3 + PANEL_WIDTH
             val contentRows = boardH + 1
-            val requiredCols = max(MIN_COLS, contentCols)
-            val requiredRows = max(MIN_ROWS, contentRows)
+            val requiredCols = maxInt(MIN_COLS, contentCols)
+            val requiredRows = maxInt(MIN_ROWS, contentRows)
             if (c < requiredCols || r < requiredRows) {
                 waitForMinimumSize(requiredCols, requiredRows)
                 clearAndHome()
@@ -689,21 +557,21 @@ if (!Console.isSupported()) {
                 return null
             }
 
-            val originCol = max(1, ((c - contentCols) / 2) + 1)
-            val originRow = max(1, ((r - contentRows) / 2) + 1)
-            LoopFrame(false, originRow, originCol)
+            val originCol = maxInt(1, ((c - contentCols) / 2) + 1)
+            val originRow = maxInt(1, ((r - contentRows) / 2) + 1)
+            LoopFrame(resized, originRow, originCol)
         }
 
         fun advanceGravity(s: GameState, frame: Int): Int {
             s.level = 1 + (s.totalLines / LEVEL_LINES_STEP)
-            val dropEvery = max(DROP_FRAMES_MIN, DROP_FRAMES_BASE - s.level)
+            val dropEvery = maxInt(DROP_FRAMES_MIN, DROP_FRAMES_BASE - s.level)
 
             var nextFrame = frame + 1
             if (nextFrame < dropEvery) return nextFrame
             nextFrame = 0
 
-            if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py + 1) == true) {
-                s.py++
+            if (canPlace(board, boardW, boardH, s.pieceId, s.rot, s.px, s.py + 1)) {
+                s.py = s.py + 1
                 return nextFrame
             }
 
@@ -711,8 +579,8 @@ if (!Console.isSupported()) {
 
             val cleared = clearCompletedLines(board, boardW, boardH)
             if (cleared > 0) {
-                s.totalLines += cleared
-                s.score += scoreForLines(cleared, s.level)
+                s.totalLines = s.totalLines + cleared
+                s.score = s.score + scoreForLines(cleared, s.level)
             }
 
             s.pieceId = s.nextId
@@ -737,59 +605,36 @@ if (!Console.isSupported()) {
             var shouldStop = false
             var prevOriginRow = -1
             var prevOriginCol = -1
-            var prevPaused = false
             while (!shouldStop) {
                 val frameData = pollLoopFrame()
                 if (frameData == null) {
                     frame = 0
-                    prevPaused = false
                     continue
                 }
 
-                val mm: Mutex = gameMutex
-                mm.withLock {
-                    if (pendingInputs.size > 0) {
-                        val toApply: List<String> = []
-                        while (pendingInputs.size > 0) {
-                            val k = pendingInputs[0]
-                            pendingInputs.removeAt(0)
-                            toApply.add(k)
+                gameMutex.withLock {
+                    if (!state.running || state.gameOver) {
+                        shouldStop = true
+                    } else {
+                        val movedOrigin = frameData.originRow != prevOriginRow || frameData.originCol != prevOriginCol
+                        if (frameData.resized || movedOrigin) {
+                            clearAndHome()
+                            prevFrameLines = []
                         }
-                        for (k in toApply) {
-                            applyKeyInput(state, k)
-                            if (!state.running || state.gameOver) break
-                        }
-                    }
-                }
-                if (!state.running || state.gameOver) {
-                    shouldStop = true
-                } else {
-                    val localForceRedraw = forceRedraw
-                    forceRedraw = false
-                    val movedOrigin = frameData.originRow != prevOriginRow || frameData.originCol != prevOriginCol
-                    if (frameData.resized || movedOrigin || localForceRedraw) {
-                        clearAndHome()
-                        prevFrameLines = []
-                    }
-                    prevOriginRow = frameData.originRow
-                    prevOriginCol = frameData.originCol
-                    if (!state.paused) {
+                        prevOriginRow = frameData.originRow
+                        prevOriginCol = frameData.originCol
                         frame = advanceGravity(state, frame)
+                        prevFrameLines = render(
+                            state,
+                            board,
+                            boardW,
+                            boardH,
+                            prevFrameLines,
+                            frameData.originRow,
+                            frameData.originCol,
+                            useColor
+                        )
                     }
-                    prevFrameLines = render(
-                        state,
-                        board,
-                        boardW,
-                        boardH,
-                        prevFrameLines,
-                        frameData.originRow,
-                        frameData.originCol,
-                        useColor
-                    )
-                    if (state.paused && (!prevPaused || frameData.resized || movedOrigin)) {
-                        renderPauseOverlay(frameData.originRow, frameData.originCol, boardW, boardH)
-                    }
-                    prevPaused = state.paused
                 }
                 Console.flush()
                 delay(FRAME_DELAY_MS)

lyngio/build.gradle.kts

@@ -112,64 +112,6 @@ kotlin {
     }
 }
 
-abstract class GenerateLyngioConsoleDecls : DefaultTask() {
-    @get:InputFile
-    @get:PathSensitive(PathSensitivity.RELATIVE)
-    abstract val sourceFile: RegularFileProperty
-
-    @get:OutputDirectory
-    abstract val outputDir: DirectoryProperty
-
-    @TaskAction
-    fun generate() {
-        val targetPkg = "net.sergeych.lyngio.stdlib_included"
-        val pkgPath = targetPkg.replace('.', '/')
-        val targetDir = outputDir.get().asFile.resolve(pkgPath)
-        targetDir.mkdirs()
-
-        val text = sourceFile.get().asFile.readText()
-        fun escapeForQuoted(s: String): String = buildString {
-            for (ch in s) when (ch) {
-                '\\' -> append("\\\\")
-                '"' -> append("\\\"")
-                '\n' -> append("\\n")
-                '\r' -> {}
-                '\t' -> append("\\t")
-                else -> append(ch)
-            }
-        }
-
-        val out = buildString {
-            append("package ").append(targetPkg).append("\n\n")
-            append("@Suppress(\"Unused\", \"MemberVisibilityCanBePrivate\")\n")
-            append("internal val consoleLyng = \"")
-            append(escapeForQuoted(text))
-            append("\"\n")
-        }
-        targetDir.resolve("console_types_lyng.generated.kt").writeText(out)
-    }
-}
-
-val lyngioConsoleDeclsFile = layout.projectDirectory.file("stdlib/lyng/io/console.lyng")
-val generatedLyngioDeclsDir = layout.buildDirectory.dir("generated/source/lyngioDecls/commonMain/kotlin")
-
-val generateLyngioConsoleDecls by tasks.registering(GenerateLyngioConsoleDecls::class) {
-    sourceFile.set(lyngioConsoleDeclsFile)
-    outputDir.set(generatedLyngioDeclsDir)
-}
-
-kotlin.sourceSets.named("commonMain") {
-    kotlin.srcDir(generateLyngioConsoleDecls)
-}
-
-kotlin.targets.configureEach {
-    compilations.configureEach {
-        compileTaskProvider.configure {
-            dependsOn(generateLyngioConsoleDecls)
-        }
-    }
-}
-
 android {
     namespace = "net.sergeych.lyngio"
     compileSdk = libs.versions.android.compileSdk.get().toInt()

lyngio/src/commonMain/kotlin/net/sergeych/lyng/io/console/LyngConsoleModule.kt

@@ -20,11 +20,9 @@ package net.sergeych.lyng.io.console
 import net.sergeych.lyng.ModuleScope
 import net.sergeych.lyng.Scope
 import net.sergeych.lyng.ScopeFacade
-import net.sergeych.lyng.Source
+import net.sergeych.lyng.miniast.*
 import net.sergeych.lyng.obj.Obj
 import net.sergeych.lyng.obj.ObjBool
-import net.sergeych.lyng.obj.ObjEnumClass
-import net.sergeych.lyng.obj.ObjEnumEntry
 import net.sergeych.lyng.obj.ObjIterable
 import net.sergeych.lyng.obj.ObjIterationFinishedException
 import net.sergeych.lyng.obj.ObjIterator
@@ -37,13 +35,13 @@ import net.sergeych.lyng.obj.toObj
 import net.sergeych.lyng.pacman.ImportManager
 import net.sergeych.lyng.raiseIllegalOperation
 import net.sergeych.lyng.requireScope
-import net.sergeych.lyngio.console.*
+import net.sergeych.lyngio.console.ConsoleEvent
+import net.sergeych.lyngio.console.ConsoleEventSource
+import net.sergeych.lyngio.console.LyngConsole
+import net.sergeych.lyngio.console.getSystemConsole
 import net.sergeych.lyngio.console.security.ConsoleAccessDeniedException
 import net.sergeych.lyngio.console.security.ConsoleAccessPolicy
 import net.sergeych.lyngio.console.security.LyngConsoleSecured
-import net.sergeych.lyngio.stdlib_included.consoleLyng
-
-private const val CONSOLE_MODULE_NAME = "lyng.io.console"
 
 /**
  * Install Lyng module `lyng.io.console` into the given scope's ImportManager.
@@ -55,9 +53,10 @@ fun createConsole(policy: ConsoleAccessPolicy, scope: Scope): Boolean = createCo
 
 /** Same as [createConsoleModule] but with explicit [ImportManager]. */
 fun createConsoleModule(policy: ConsoleAccessPolicy, manager: ImportManager): Boolean {
-    if (manager.packageNames.contains(CONSOLE_MODULE_NAME)) return false
+    val name = "lyng.io.console"
+    if (manager.packageNames.contains(name)) return false
 
-    manager.addPackage(CONSOLE_MODULE_NAME) { module ->
+    manager.addPackage(name) { module ->
         buildConsoleModule(module, policy)
     }
     return true
@@ -66,37 +65,59 @@ fun createConsoleModule(policy: ConsoleAccessPolicy, manager: ImportManager): Bo
 fun createConsole(policy: ConsoleAccessPolicy, manager: ImportManager): Boolean = createConsoleModule(policy, manager)
 
 private suspend fun buildConsoleModule(module: ModuleScope, policy: ConsoleAccessPolicy) {
-    // Load Lyng declarations for console enums/types first (module-local source of truth).
-    module.eval(Source(CONSOLE_MODULE_NAME, consoleLyng))
-    ConsoleEnums.initialize(module)
     val console: LyngConsole = LyngConsoleSecured(getSystemConsole(), policy)
 
     val consoleType = object : net.sergeych.lyng.obj.ObjClass("Console") {}
 
     consoleType.apply {
-        addClassFn("isSupported") {
+        addClassFnDoc(
+            name = "isSupported",
+            doc = "Whether console control API is supported on this platform.",
+            returns = type("lyng.Bool"),
+            moduleName = module.packageName
+        ) {
             ObjBool(console.isSupported)
         }
 
-        addClassFn("isTty") {
+        addClassFnDoc(
+            name = "isTty",
+            doc = "Whether current stdout is attached to an interactive TTY.",
+            returns = type("lyng.Bool"),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 ObjBool(console.isTty())
             }
         }
 
-        addClassFn("ansiLevel") {
+        addClassFnDoc(
+            name = "ansiLevel",
+            doc = "Detected ANSI color capability: NONE, BASIC16, ANSI256, TRUECOLOR.",
+            returns = type("lyng.String"),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
-                ConsoleEnums.ansiLevel(console.ansiLevel().name)
+                ObjString(console.ansiLevel().name)
             }
         }
 
-        addClassFn("geometry") {
+        addClassFnDoc(
+            name = "geometry",
+            doc = "Current terminal geometry or null.",
+            returns = type("ConsoleGeometry", nullable = true),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.geometry()?.let { ObjConsoleGeometry(it.columns, it.rows) } ?: ObjNull
             }
         }
 
-        addClassFn("details") {
+        addClassFnDoc(
+            name = "details",
+            doc = "Get consolidated console details.",
+            returns = type("ConsoleDetails"),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 val tty = console.isTty()
                 val ansi = console.ansiLevel()
@@ -104,13 +125,18 @@ private suspend fun buildConsoleModule(module: ModuleScope, policy: ConsoleAcces
                 ObjConsoleDetails(
                     supported = console.isSupported,
                     isTty = tty,
-                    ansiLevel = ConsoleEnums.ansiLevel(ansi.name),
+                    ansiLevel = ansi.name,
                     geometry = geometry?.let { ObjConsoleGeometry(it.columns, it.rows) },
                 )
             }
         }
 
-        addClassFn("write") {
+        addClassFnDoc(
+            name = "write",
+            doc = "Write text directly to console output.",
+            params = listOf(ParamDoc("text", type("lyng.String"))),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 val text = requiredArg<ObjString>(0).value
                 console.write(text)
@@ -118,28 +144,48 @@ private suspend fun buildConsoleModule(module: ModuleScope, policy: ConsoleAcces
             }
         }
 
-        addClassFn("flush") {
+        addClassFnDoc(
+            name = "flush",
+            doc = "Flush console output buffer.",
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.flush()
                 ObjVoid
             }
         }
 
-        addClassFn("home") {
+        addClassFnDoc(
+            name = "home",
+            doc = "Move cursor to home position (1,1).",
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.write("\u001B[H")
                 ObjVoid
             }
         }
 
-        addClassFn("clear") {
+        addClassFnDoc(
+            name = "clear",
+            doc = "Clear the visible screen buffer.",
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.write("\u001B[2J")
                 ObjVoid
             }
         }
 
-        addClassFn("moveTo") {
+        addClassFnDoc(
+            name = "moveTo",
+            doc = "Move cursor to 1-based row and column.",
+            params = listOf(
+                ParamDoc("row", type("lyng.Int")),
+                ParamDoc("column", type("lyng.Int")),
+            ),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 val row = requiredArg<net.sergeych.lyng.obj.ObjInt>(0).value
                 val col = requiredArg<net.sergeych.lyng.obj.ObjInt>(1).value
@@ -148,28 +194,45 @@ private suspend fun buildConsoleModule(module: ModuleScope, policy: ConsoleAcces
             }
         }
 
-        addClassFn("clearLine") {
+        addClassFnDoc(
+            name = "clearLine",
+            doc = "Clear the current line.",
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.write("\u001B[2K")
                 ObjVoid
             }
         }
 
-        addClassFn("enterAltScreen") {
+        addClassFnDoc(
+            name = "enterAltScreen",
+            doc = "Switch to terminal alternate screen buffer.",
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.write("\u001B[?1049h")
                 ObjVoid
             }
         }
 
-        addClassFn("leaveAltScreen") {
+        addClassFnDoc(
+            name = "leaveAltScreen",
+            doc = "Return from alternate screen buffer to normal screen.",
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.write("\u001B[?1049l")
                 ObjVoid
             }
         }
 
-        addClassFn("setCursorVisible") {
+        addClassFnDoc(
+            name = "setCursorVisible",
+            doc = "Show or hide the terminal cursor.",
+            params = listOf(ParamDoc("visible", type("lyng.Bool"))),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 val visible = requiredArg<ObjBool>(0).value
                 console.write(if (visible) "\u001B[?25h" else "\u001B[?25l")
@@ -177,13 +240,24 @@ private suspend fun buildConsoleModule(module: ModuleScope, policy: ConsoleAcces
             }
         }
 
-        addClassFn("events") {
+        addClassFnDoc(
+            name = "events",
+            doc = "Endless iterable console event source (resize, keydown, keyup). Use in a loop, often inside launch.",
+            returns = type("ConsoleEventStream"),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 console.events().toConsoleEventStream()
             }
         }
 
-        addClassFn("setRawMode") {
+        addClassFnDoc(
+            name = "setRawMode",
+            doc = "Enable or disable raw keyboard mode. Returns true if mode changed.",
+            params = listOf(ParamDoc("enabled", type("lyng.Bool"))),
+            returns = type("lyng.Bool"),
+            moduleName = module.packageName
+        ) {
             consoleGuard {
                 val enabled = requiredArg<ObjBool>(0).value
                 ObjBool(console.setRawMode(enabled))
@@ -191,13 +265,55 @@ private suspend fun buildConsoleModule(module: ModuleScope, policy: ConsoleAcces
         }
     }
 
-    module.addConst("Console", consoleType)
-    module.addConst("ConsoleGeometry", ObjConsoleGeometry.type)
-    module.addConst("ConsoleDetails", ObjConsoleDetails.type)
-    module.addConst("ConsoleEvent", ObjConsoleEvent.type)
-    module.addConst("ConsoleResizeEvent", ObjConsoleResizeEvent.type)
-    module.addConst("ConsoleKeyEvent", ObjConsoleKeyEvent.typeObj)
-    module.addConst("ConsoleEventStream", ObjConsoleEventStream.type)
+    module.addConstDoc(
+        name = "Console",
+        value = consoleType,
+        doc = "Console runtime API.",
+        type = type("Console"),
+        moduleName = module.packageName
+    )
+    module.addConstDoc(
+        name = "ConsoleGeometry",
+        value = ObjConsoleGeometry.type,
+        doc = "Terminal geometry.",
+        type = type("lyng.Class"),
+        moduleName = module.packageName
+    )
+    module.addConstDoc(
+        name = "ConsoleDetails",
+        value = ObjConsoleDetails.type,
+        doc = "Consolidated console capability details.",
+        type = type("lyng.Class"),
+        moduleName = module.packageName
+    )
+    module.addConstDoc(
+        name = "ConsoleEvent",
+        value = ObjConsoleEvent.type,
+        doc = "Base class for console events.",
+        type = type("lyng.Class"),
+        moduleName = module.packageName
+    )
+    module.addConstDoc(
+        name = "ConsoleResizeEvent",
+        value = ObjConsoleResizeEvent.type,
+        doc = "Terminal resize event.",
+        type = type("lyng.Class"),
+        moduleName = module.packageName
+    )
+    module.addConstDoc(
+        name = "ConsoleKeyEvent",
+        value = ObjConsoleKeyEvent.typeObj,
+        doc = "Keyboard event.",
+        type = type("lyng.Class"),
+        moduleName = module.packageName
+    )
+    module.addConstDoc(
+        name = "ConsoleEventStream",
+        value = ObjConsoleEventStream.type,
+        doc = "Endless iterable stream of console events.",
+        type = type("lyng.Class"),
+        moduleName = module.packageName
+    )
 }
 
 private suspend inline fun ScopeFacade.consoleGuard(crossinline block: suspend () -> Obj): Obj {
@@ -222,7 +338,12 @@ private class ObjConsoleEventStream(
 
     companion object {
         val type = net.sergeych.lyng.obj.ObjClass("ConsoleEventStream", ObjIterable).apply {
-            addFn("iterator") {
+            addFnDoc(
+                name = "iterator",
+                doc = "Create an iterator over incoming console events.",
+                returns = type("lyng.Iterator"),
+                moduleName = "lyng.io.console",
+            ) {
                 val stream = thisAs<ObjConsoleEventStream>()
                 ObjConsoleEventIterator(stream.source)
             }
@@ -242,36 +363,19 @@ private class ObjConsoleEventIterator(
     private suspend fun ensureCached(): Boolean {
         if (closed) return false
         if (cached != null) return true
-        while (!closed && cached == null) {
-            val event = try {
-                source.nextEvent()
-            } catch (e: Throwable) {
-                // Consumer loops must survive source/read failures: report and keep polling.
-                consoleFlowDebug("console-bridge: nextEvent failed; dropping failure and continuing", e)
-                continue
-            }
-            if (event == null) {
-                closeSource()
-                return false
-            }
-            cached = try {
-                event.toObjEvent()
-            } catch (e: Throwable) {
-                // Malformed/native event payload must not terminate consumer iteration.
-                consoleFlowDebug("console-bridge: malformed event dropped: $event", e)
-                null
-            }
+        val event = source.nextEvent()
+        if (event == null) {
+            closeSource()
+            return false
         }
-        return cached != null
+        cached = event.toObjEvent()
+        return true
     }
 
     private suspend fun closeSource() {
         if (closed) return
         closed = true
-        // Do not close the underlying console source from VM iterator cancellation.
-        // CmdFrame.cancelIterators() may call cancelIteration() while user code is still
-        // expected to keep processing input (e.g. recover from app-level exceptions).
-        // The source lifecycle is managed by the console runtime.
+        source.close()
     }
 
     suspend fun hasNext(): Boolean = ensureCached()
@@ -287,13 +391,28 @@ private class ObjConsoleEventIterator(
 
     companion object {
         val type = net.sergeych.lyng.obj.ObjClass("ConsoleEventIterator", ObjIterator).apply {
-            addFn("hasNext") {
+            addFnDoc(
+                name = "hasNext",
+                doc = "Whether another console event is available.",
+                returns = type("lyng.Bool"),
+                moduleName = "lyng.io.console",
+            ) {
                 thisAs<ObjConsoleEventIterator>().hasNext().toObj()
             }
-            addFn("next") {
+            addFnDoc(
+                name = "next",
+                doc = "Return the next console event.",
+                returns = type("ConsoleEvent"),
+                moduleName = "lyng.io.console",
+            ) {
                 thisAs<ObjConsoleEventIterator>().next(requireScope())
             }
-            addFn("cancelIteration") {
+            addFnDoc(
+                name = "cancelIteration",
+                doc = "Stop reading console events and release resources.",
+                returns = type("lyng.Void"),
+                moduleName = "lyng.io.console",
+            ) {
                 thisAs<ObjConsoleEventIterator>().closeSource()
                 ObjVoid
             }
@@ -303,119 +422,27 @@ private class ObjConsoleEventIterator(
 
 private fun ConsoleEvent.toObjEvent(): Obj = when (this) {
     is ConsoleEvent.Resize -> ObjConsoleResizeEvent(columns, rows)
-    is ConsoleEvent.KeyDown -> ObjConsoleKeyEvent(type = ConsoleEnums.KEY_DOWN, key = sanitizedKeyOrFallback(key), codeName = code, ctrl = ctrl, alt = alt, shift = shift, meta = meta)
-    is ConsoleEvent.KeyUp -> ObjConsoleKeyEvent(type = ConsoleEnums.KEY_UP, key = sanitizedKeyOrFallback(key), codeName = code, ctrl = ctrl, alt = alt, shift = shift, meta = meta)
-}
-
-private fun sanitizedKeyOrFallback(key: String): String {
-    if (key.isNotEmpty()) return key
-    consoleFlowDebug("console-bridge: empty key value received; using fallback key name")
-    return "Unknown"
-}
-
-private object ConsoleEnums {
-    lateinit var eventTypeClass: ObjEnumClass
-        private set
-    lateinit var keyCodeClass: ObjEnumClass
-        private set
-    lateinit var ansiLevelClass: ObjEnumClass
-        private set
-
-    private lateinit var eventEntries: Map<String, ObjEnumEntry>
-    private lateinit var keyCodeEntries: Map<String, ObjEnumEntry>
-    private lateinit var ansiLevelEntries: Map<String, ObjEnumEntry>
-
-    val UNKNOWN: ObjEnumEntry get() = event("UNKNOWN")
-    val RESIZE: ObjEnumEntry get() = event("RESIZE")
-    val KEY_DOWN: ObjEnumEntry get() = event("KEY_DOWN")
-    val KEY_UP: ObjEnumEntry get() = event("KEY_UP")
-    val CODE_UNKNOWN: ObjEnumEntry get() = code("UNKNOWN")
-    val CHARACTER: ObjEnumEntry get() = code("CHARACTER")
-
-    fun initialize(module: ModuleScope) {
-        eventTypeClass = resolveEnum(module, "ConsoleEventType")
-        keyCodeClass = resolveEnum(module, "ConsoleKeyCode")
-        ansiLevelClass = resolveEnum(module, "ConsoleAnsiLevel")
-        eventEntries = resolveEntries(
-            eventTypeClass,
-            listOf("UNKNOWN", "RESIZE", "KEY_DOWN", "KEY_UP")
-        )
-        keyCodeEntries = resolveEntries(
-            keyCodeClass,
-            listOf(
-                "UNKNOWN", "CHARACTER", "ARROW_UP", "ARROW_DOWN", "ARROW_LEFT", "ARROW_RIGHT",
-                "HOME", "END", "INSERT", "DELETE", "PAGE_UP", "PAGE_DOWN",
-                "ESCAPE", "ENTER", "TAB", "BACKSPACE", "SPACE"
-            )
-        )
-        ansiLevelEntries = resolveEntries(
-            ansiLevelClass,
-            listOf("NONE", "BASIC16", "ANSI256", "TRUECOLOR")
-        )
-    }
-
-    private fun resolveEnum(module: ModuleScope, enumName: String): ObjEnumClass {
-        val local = module.get(enumName)?.value as? ObjEnumClass
-        if (local != null) return local
-        val root = module.importProvider.rootScope.get(enumName)?.value as? ObjEnumClass
-        return root ?: error("lyng.io.console declaration enum is missing: $enumName")
-    }
-
-    private fun resolveEntries(enumClass: ObjEnumClass, names: List<String>): Map<String, ObjEnumEntry> {
-        return names.associateWith { name ->
-            (enumClass.byName[ObjString(name)] as? ObjEnumEntry)
-                ?: error("lyng.io.console enum entry is missing: ${enumClass.className}.$name")
-        }
-    }
-
-    fun event(name: String): ObjEnumEntry = eventEntries[name]
-        ?: error("lyng.io.console enum entry is missing: ${eventTypeClass.className}.$name")
-
-    fun code(name: String): ObjEnumEntry = keyCodeEntries[name]
-        ?: error("lyng.io.console enum entry is missing: ${keyCodeClass.className}.$name")
-
-    fun ansiLevel(name: String): ObjEnumEntry = ansiLevelEntries[name]
-        ?: error("lyng.io.console enum entry is missing: ${ansiLevelClass.className}.$name")
-}
-
-private val KEY_CODE_BY_KEY_NAME = mapOf(
-    "ArrowUp" to "ARROW_UP",
-    "ArrowDown" to "ARROW_DOWN",
-    "ArrowLeft" to "ARROW_LEFT",
-    "ArrowRight" to "ARROW_RIGHT",
-    "Home" to "HOME",
-    "End" to "END",
-    "Insert" to "INSERT",
-    "Delete" to "DELETE",
-    "PageUp" to "PAGE_UP",
-    "PageDown" to "PAGE_DOWN",
-    "Escape" to "ESCAPE",
-    "Enter" to "ENTER",
-    "Tab" to "TAB",
-    "Backspace" to "BACKSPACE",
-    " " to "SPACE",
-)
-
-private fun codeFrom(key: String, codeName: String?): ObjEnumEntry {
-    val resolved = KEY_CODE_BY_KEY_NAME[codeName ?: key]
-    return when {
-        resolved != null -> ConsoleEnums.code(resolved)
-        key.length == 1 -> ConsoleEnums.CHARACTER
-        else -> ConsoleEnums.CODE_UNKNOWN
-    }
+    is ConsoleEvent.KeyDown -> ObjConsoleKeyEvent(type = "keydown", key = key, code = code, ctrl = ctrl, alt = alt, shift = shift, meta = meta)
+    is ConsoleEvent.KeyUp -> ObjConsoleKeyEvent(type = "keyup", key = key, code = code, ctrl = ctrl, alt = alt, shift = shift, meta = meta)
 }
 
 private abstract class ObjConsoleEventBase(
-    private val type: ObjEnumEntry,
+    private val eventType: String,
     final override val objClass: net.sergeych.lyng.obj.ObjClass,
 ) : Obj() {
-    fun type(): ObjEnumEntry = type
+    fun eventTypeName(): String = eventType
 }
 
-private class ObjConsoleEvent : ObjConsoleEventBase(ConsoleEnums.UNKNOWN, type) {
+private class ObjConsoleEvent : ObjConsoleEventBase("event", type) {
     companion object {
         val type = net.sergeych.lyng.obj.ObjClass("ConsoleEvent").apply {
-            addProperty(name = "type", getter = { (this.thisObj as ObjConsoleEventBase).type() })
+            addPropertyDoc(
+                name = "type",
+                doc = "Event type string: resize, keydown, keyup.",
+                type = type("lyng.String"),
+                moduleName = "lyng.io.console",
+                getter = { ObjString((this.thisObj as ObjConsoleEventBase).eventTypeName()) }
+            )
         }
     }
 }
@@ -423,40 +450,83 @@ private class ObjConsoleEvent : ObjConsoleEventBase(ConsoleEnums.UNKNOWN, type)
 private class ObjConsoleResizeEvent(
     val columns: Int,
     val rows: Int,
-) : ObjConsoleEventBase(ConsoleEnums.RESIZE, type) {
+) : ObjConsoleEventBase("resize", type) {
     companion object {
         val type = net.sergeych.lyng.obj.ObjClass("ConsoleResizeEvent", ObjConsoleEvent.type).apply {
-            addProperty(name = "columns", getter = { (this.thisObj as ObjConsoleResizeEvent).columns.toObj() })
-            addProperty(name = "rows", getter = { (this.thisObj as ObjConsoleResizeEvent).rows.toObj() })
+            addPropertyDoc(
+                name = "columns",
+                doc = "Terminal width in character cells.",
+                type = type("lyng.Int"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleResizeEvent).columns.toObj() }
+            )
+            addPropertyDoc(
+                name = "rows",
+                doc = "Terminal height in character cells.",
+                type = type("lyng.Int"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleResizeEvent).rows.toObj() }
+            )
         }
     }
 }
 
 private class ObjConsoleKeyEvent(
-    type: ObjEnumEntry,
+    type: String,
     val key: String,
-    val codeName: String?,
+    val code: String?,
     val ctrl: Boolean,
     val alt: Boolean,
     val shift: Boolean,
     val meta: Boolean,
 ) : ObjConsoleEventBase(type, typeObj) {
-    init {
-        require(key.isNotEmpty()) { "ConsoleKeyEvent.key must never be empty" }
-    }
-
     companion object {
         val typeObj = net.sergeych.lyng.obj.ObjClass("ConsoleKeyEvent", ObjConsoleEvent.type).apply {
-            addProperty(name = "key", getter = { ObjString((this.thisObj as ObjConsoleKeyEvent).key) })
-            addProperty(name = "code", getter = { codeFrom((this.thisObj as ObjConsoleKeyEvent).key, (this.thisObj as ObjConsoleKeyEvent).codeName) })
-            addProperty(name = "codeName", getter = {
-                val code = (this.thisObj as ObjConsoleKeyEvent).codeName
-                code?.let(::ObjString) ?: ObjNull
-            })
-            addProperty(name = "ctrl", getter = { (this.thisObj as ObjConsoleKeyEvent).ctrl.toObj() })
-            addProperty(name = "alt", getter = { (this.thisObj as ObjConsoleKeyEvent).alt.toObj() })
-            addProperty(name = "shift", getter = { (this.thisObj as ObjConsoleKeyEvent).shift.toObj() })
-            addProperty(name = "meta", getter = { (this.thisObj as ObjConsoleKeyEvent).meta.toObj() })
+            addPropertyDoc(
+                name = "key",
+                doc = "Logical key name (e.g. ArrowLeft, a, Escape).",
+                type = type("lyng.String"),
+                moduleName = "lyng.io.console",
+                getter = { ObjString((this.thisObj as ObjConsoleKeyEvent).key) }
+            )
+            addPropertyDoc(
+                name = "code",
+                doc = "Optional hardware/code identifier.",
+                type = type("lyng.String", nullable = true),
+                moduleName = "lyng.io.console",
+                getter = {
+                    val code = (this.thisObj as ObjConsoleKeyEvent).code
+                    code?.let(::ObjString) ?: ObjNull
+                }
+            )
+            addPropertyDoc(
+                name = "ctrl",
+                doc = "Whether Ctrl modifier is pressed.",
+                type = type("lyng.Bool"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleKeyEvent).ctrl.toObj() }
+            )
+            addPropertyDoc(
+                name = "alt",
+                doc = "Whether Alt modifier is pressed.",
+                type = type("lyng.Bool"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleKeyEvent).alt.toObj() }
+            )
+            addPropertyDoc(
+                name = "shift",
+                doc = "Whether Shift modifier is pressed.",
+                type = type("lyng.Bool"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleKeyEvent).shift.toObj() }
+            )
+            addPropertyDoc(
+                name = "meta",
+                doc = "Whether Meta/Super modifier is pressed.",
+                type = type("lyng.Bool"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleKeyEvent).meta.toObj() }
+            )
         }
     }
 }
@@ -469,8 +539,20 @@ private class ObjConsoleGeometry(
 
     companion object {
         val type = net.sergeych.lyng.obj.ObjClass("ConsoleGeometry").apply {
-            addProperty(name = "columns", getter = { (this.thisObj as ObjConsoleGeometry).columns.toObj() })
-            addProperty(name = "rows", getter = { (this.thisObj as ObjConsoleGeometry).rows.toObj() })
+            addPropertyDoc(
+                name = "columns",
+                doc = "Terminal width in character cells.",
+                type = type("lyng.Int"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleGeometry).columns.toObj() }
+            )
+            addPropertyDoc(
+                name = "rows",
+                doc = "Terminal height in character cells.",
+                type = type("lyng.Int"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleGeometry).rows.toObj() }
+            )
         }
     }
 }
@@ -478,17 +560,41 @@ private class ObjConsoleGeometry(
 private class ObjConsoleDetails(
     val supported: Boolean,
     val isTty: Boolean,
-    val ansiLevel: ObjEnumEntry,
+    val ansiLevel: String,
     val geometry: ObjConsoleGeometry?,
 ) : Obj() {
     override val objClass: net.sergeych.lyng.obj.ObjClass get() = type
 
     companion object {
         val type = net.sergeych.lyng.obj.ObjClass("ConsoleDetails").apply {
-            addProperty(name = "supported", getter = { (this.thisObj as ObjConsoleDetails).supported.toObj() })
-            addProperty(name = "isTty", getter = { (this.thisObj as ObjConsoleDetails).isTty.toObj() })
-            addProperty(name = "ansiLevel", getter = { (this.thisObj as ObjConsoleDetails).ansiLevel })
-            addProperty(name = "geometry", getter = { (this.thisObj as ObjConsoleDetails).geometry ?: ObjNull })
+            addPropertyDoc(
+                name = "supported",
+                doc = "Whether console API is supported.",
+                type = type("lyng.Bool"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleDetails).supported.toObj() }
+            )
+            addPropertyDoc(
+                name = "isTty",
+                doc = "Whether output is connected to a TTY.",
+                type = type("lyng.Bool"),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleDetails).isTty.toObj() }
+            )
+            addPropertyDoc(
+                name = "ansiLevel",
+                doc = "Detected ANSI color capability level.",
+                type = type("lyng.String"),
+                moduleName = "lyng.io.console",
+                getter = { ObjString((this.thisObj as ObjConsoleDetails).ansiLevel) }
+            )
+            addPropertyDoc(
+                name = "geometry",
+                doc = "Current terminal geometry or null.",
+                type = type("ConsoleGeometry", nullable = true),
+                moduleName = "lyng.io.console",
+                getter = { (this.thisObj as ObjConsoleDetails).geometry ?: ObjNull }
+            )
         }
     }
 }

lyngio/src/commonMain/kotlin/net/sergeych/lyngio/console/MordantLyngConsole.kt

@@ -100,9 +100,8 @@ object MordantLyngConsole : LyngConsole {
         var running = true
 
         globalLaunch {
-        val initialSize = runCatching { t.updateSize() }.getOrNull()
-        var lastWidth = initialSize?.width ?: 0
-        var lastHeight = initialSize?.height ?: 0
+        var lastWidth = t.updateSize().width
+        var lastHeight = t.updateSize().height
         val startMark = TimeSource.Monotonic.markNow()
         var lastHeartbeatMark = startMark
         var loops = 0L
@@ -114,18 +113,6 @@ object MordantLyngConsole : LyngConsole {
         var lastKeyMark = startMark
         var lastRawRecoveryMark = startMark
 
-        fun tryEmitResize(width: Int, height: Int) {
-            if (width < 1 || height < 1) {
-                consoleFlowDebug("events: ignored invalid resize width=$width height=$height")
-                return
-            }
-            if (width == lastWidth && height == lastHeight) return
-            out.trySend(ConsoleEvent.Resize(width, height))
-            lastWidth = width
-            lastHeight = height
-            resizeEvents += 1
-        }
-
         consoleFlowDebug("events: collector started")
         try {
             while (currentCoroutineContext().isActive && sourceState.withLock { running }) {
@@ -135,7 +122,12 @@ object MordantLyngConsole : LyngConsole {
                     delay(150)
                     continue
                 }
-                tryEmitResize(currentSize.width, currentSize.height)
+                if (currentSize.width != lastWidth || currentSize.height != lastHeight) {
+                    out.trySend(ConsoleEvent.Resize(currentSize.width, currentSize.height))
+                    lastWidth = currentSize.width
+                    lastHeight = currentSize.height
+                    resizeEvents += 1
+                }
 
                 val raw = stateMutex.withLock {
                     if (!rawModeRequested) {
@@ -181,8 +173,10 @@ object MordantLyngConsole : LyngConsole {
                 val ev = readResult.getOrNull()
 
                 val resized = runCatching { t.updateSize() }.getOrNull()
-                if (resized != null) {
-                    tryEmitResize(resized.width, resized.height)
+                if (resized != null && (resized.width != lastWidth || resized.height != lastHeight)) {
+                    out.trySend(ConsoleEvent.Resize(resized.width, resized.height))
+                    lastWidth = resized.width
+                    lastHeight = resized.height
                 }
 
                 when (ev) {

lyngio/src/commonMain/kotlin/net/sergeych/lyngio/docs/ConsoleBuiltinDocs.kt

@@ -17,12 +17,248 @@
 
 package net.sergeych.lyngio.docs
 
-/**
- * Console docs are declared in `lyngio/stdlib/lyng/io/console.lyng`.
- * Keep this shim for compatibility with reflective loaders.
- */
+import net.sergeych.lyng.miniast.BuiltinDocRegistry
+import net.sergeych.lyng.miniast.ParamDoc
+import net.sergeych.lyng.miniast.type
+
 object ConsoleBuiltinDocs {
+    private var registered = false
+
     fun ensure() {
-        // No Kotlin-side doc registration: console.lyng is the source of truth.
+        if (registered) return
+        BuiltinDocRegistry.module("lyng.io.console") {
+            classDoc(
+                name = "Console",
+                doc = "Console runtime API."
+            ) {
+                method(
+                    name = "isSupported",
+                    doc = "Whether console control API is supported on this platform.",
+                    returns = type("lyng.Bool"),
+                    isStatic = true
+                )
+                method(
+                    name = "isTty",
+                    doc = "Whether stdout is attached to an interactive TTY.",
+                    returns = type("lyng.Bool"),
+                    isStatic = true
+                )
+                method(
+                    name = "ansiLevel",
+                    doc = "Detected ANSI color capability: NONE, BASIC16, ANSI256, TRUECOLOR.",
+                    returns = type("lyng.String"),
+                    isStatic = true
+                )
+                method(
+                    name = "geometry",
+                    doc = "Current terminal geometry or null.",
+                    returns = type("ConsoleGeometry", nullable = true),
+                    isStatic = true
+                )
+                method(
+                    name = "details",
+                    doc = "Get consolidated console details.",
+                    returns = type("ConsoleDetails"),
+                    isStatic = true
+                )
+                method(
+                    name = "write",
+                    doc = "Write text directly to console output.",
+                    params = listOf(ParamDoc("text", type("lyng.String"))),
+                    isStatic = true
+                )
+                method(
+                    name = "flush",
+                    doc = "Flush console output buffer.",
+                    isStatic = true
+                )
+                method(
+                    name = "home",
+                    doc = "Move cursor to home position (1,1).",
+                    isStatic = true
+                )
+                method(
+                    name = "clear",
+                    doc = "Clear the visible screen buffer.",
+                    isStatic = true
+                )
+                method(
+                    name = "moveTo",
+                    doc = "Move cursor to 1-based row and column.",
+                    params = listOf(
+                        ParamDoc("row", type("lyng.Int")),
+                        ParamDoc("column", type("lyng.Int")),
+                    ),
+                    isStatic = true
+                )
+                method(
+                    name = "clearLine",
+                    doc = "Clear the current line.",
+                    isStatic = true
+                )
+                method(
+                    name = "enterAltScreen",
+                    doc = "Switch to terminal alternate screen buffer.",
+                    isStatic = true
+                )
+                method(
+                    name = "leaveAltScreen",
+                    doc = "Return from alternate screen buffer to normal screen.",
+                    isStatic = true
+                )
+                method(
+                    name = "setCursorVisible",
+                    doc = "Show or hide the terminal cursor.",
+                    params = listOf(ParamDoc("visible", type("lyng.Bool"))),
+                    isStatic = true
+                )
+                method(
+                    name = "events",
+                    doc = "Endless iterable console event source (resize, keydown, keyup). Use in a loop, often inside launch.",
+                    returns = type("ConsoleEventStream"),
+                    isStatic = true
+                )
+                method(
+                    name = "setRawMode",
+                    doc = "Enable or disable raw keyboard mode. Returns true if mode changed.",
+                    params = listOf(ParamDoc("enabled", type("lyng.Bool"))),
+                    returns = type("lyng.Bool"),
+                    isStatic = true
+                )
+            }
+            classDoc(
+                name = "ConsoleEventStream",
+                doc = "Endless iterable stream of console events."
+            ) {
+                method(
+                    name = "iterator",
+                    doc = "Create an iterator over incoming console events.",
+                    returns = type("lyng.Iterator")
+                )
+            }
+            classDoc(
+                name = "ConsoleGeometry",
+                doc = "Terminal geometry."
+            ) {
+                field(
+                    name = "columns",
+                    doc = "Terminal width in character cells.",
+                    type = type("lyng.Int")
+                )
+                field(
+                    name = "rows",
+                    doc = "Terminal height in character cells.",
+                    type = type("lyng.Int")
+                )
+            }
+            classDoc(
+                name = "ConsoleDetails",
+                doc = "Consolidated console capability details."
+            ) {
+                field(
+                    name = "supported",
+                    doc = "Whether console API is supported.",
+                    type = type("lyng.Bool")
+                )
+                field(
+                    name = "isTty",
+                    doc = "Whether output is attached to a TTY.",
+                    type = type("lyng.Bool")
+                )
+                field(
+                    name = "ansiLevel",
+                    doc = "Detected ANSI color capability.",
+                    type = type("lyng.String")
+                )
+                field(
+                    name = "geometry",
+                    doc = "Current geometry or null.",
+                    type = type("ConsoleGeometry", nullable = true)
+                )
+            }
+            classDoc(
+                name = "ConsoleEvent",
+                doc = "Base class for console events."
+            ) {
+                field(
+                    name = "type",
+                    doc = "Event kind string.",
+                    type = type("lyng.String")
+                )
+            }
+            classDoc(
+                name = "ConsoleResizeEvent",
+                doc = "Resize event."
+            ) {
+                field(
+                    name = "type",
+                    doc = "Event kind string: resize.",
+                    type = type("lyng.String")
+                )
+                field(
+                    name = "columns",
+                    doc = "Terminal width in character cells.",
+                    type = type("lyng.Int")
+                )
+                field(
+                    name = "rows",
+                    doc = "Terminal height in character cells.",
+                    type = type("lyng.Int")
+                )
+            }
+            classDoc(
+                name = "ConsoleKeyEvent",
+                doc = "Keyboard event."
+            ) {
+                field(
+                    name = "type",
+                    doc = "Event kind string: keydown or keyup.",
+                    type = type("lyng.String")
+                )
+                field(
+                    name = "key",
+                    doc = "Logical key name.",
+                    type = type("lyng.String")
+                )
+                field(
+                    name = "code",
+                    doc = "Optional hardware code.",
+                    type = type("lyng.String", nullable = true)
+                )
+                field(
+                    name = "ctrl",
+                    doc = "Ctrl modifier state.",
+                    type = type("lyng.Bool")
+                )
+                field(
+                    name = "alt",
+                    doc = "Alt modifier state.",
+                    type = type("lyng.Bool")
+                )
+                field(
+                    name = "shift",
+                    doc = "Shift modifier state.",
+                    type = type("lyng.Bool")
+                )
+                field(
+                    name = "meta",
+                    doc = "Meta modifier state.",
+                    type = type("lyng.Bool")
+                )
+            }
+
+            valDoc(
+                name = "Console",
+                doc = "Console runtime API.",
+                type = type("Console")
+            )
+            valDoc(name = "ConsoleGeometry", doc = "Terminal geometry class.", type = type("lyng.Class"))
+            valDoc(name = "ConsoleDetails", doc = "Console details class.", type = type("lyng.Class"))
+            valDoc(name = "ConsoleEvent", doc = "Base console event class.", type = type("lyng.Class"))
+            valDoc(name = "ConsoleResizeEvent", doc = "Resize event class.", type = type("lyng.Class"))
+            valDoc(name = "ConsoleKeyEvent", doc = "Keyboard event class.", type = type("lyng.Class"))
+            valDoc(name = "ConsoleEventStream", doc = "Iterable console event stream class.", type = type("lyng.Class"))
+        }
+        registered = true
     }
 }

lyngio/src/jvmMain/kotlin/net/sergeych/lyngio/console/JvmLyngConsole.kt

@@ -26,7 +26,6 @@ import org.jline.terminal.Terminal
 import org.jline.terminal.TerminalBuilder
 import org.jline.utils.NonBlockingReader
 import java.io.EOFException
-import java.io.InterruptedIOException
 import java.util.*
 import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.atomic.AtomicLong
@@ -42,7 +41,7 @@ import kotlin.time.TimeSource
  *   to avoid dual-terminal contention.
  */
 object JvmLyngConsole : LyngConsole {
-    private const val DEBUG_REVISION = "jline-r27-no-close-on-vm-iterator-cancel-2026-03-19"
+    private const val DEBUG_REVISION = "jline-r26-force-rebuild-on-noop-recovery-2026-03-19"
     private val codeSourceLocation: String by lazy {
         runCatching {
             JvmLyngConsole::class.java.protectionDomain?.codeSource?.location?.toString()
@@ -51,44 +50,6 @@ object JvmLyngConsole : LyngConsole {
 
     private val terminalRef = AtomicReference<Terminal?>(null)
     private val terminalInitLock = Any()
-    private val shutdownHook = Thread(
-        {
-            restoreTerminalStateOnShutdown()
-        },
-        "lyng-console-shutdown"
-    ).apply { isDaemon = true }
-
-    init {
-        runCatching { Runtime.getRuntime().addShutdownHook(shutdownHook) }
-            .onFailure { consoleFlowDebug("jline-events: shutdown hook install failed", it) }
-    }
-
-    private fun restoreTerminalStateOnShutdown() {
-        val term = terminalRef.get() ?: return
-        runCatching {
-            term.writer().print("\u001B[?25h")
-            term.writer().print("\u001B[?1049l")
-            term.writer().flush()
-        }.onFailure {
-            consoleFlowDebug("jline-events: shutdown visual restore failed", it)
-        }
-        val saved = if (runCatching { stateMutex.tryLock() }.getOrNull() == true) {
-            try {
-                rawModeRequested = false
-                val s = rawSavedAttributes
-                rawSavedAttributes = null
-                s
-            } finally {
-                stateMutex.unlock()
-            }
-        } else {
-            null
-        }
-        if (saved != null) {
-            runCatching { term.setAttributes(saved) }
-                .onFailure { consoleFlowDebug("jline-events: shutdown raw attrs restore failed", it) }
-        }
-    }
 
     private fun currentTerminal(): Terminal? {
         val existing = terminalRef.get()
@@ -215,29 +176,10 @@ object JvmLyngConsole : LyngConsole {
         var reader = activeTerm.reader()
         var keyThread: Thread? = null
         var heartbeatThread: Thread? = null
-        val resizeEmitMutex = Any()
-        var lastResizeCols = Int.MIN_VALUE
-        var lastResizeRows = Int.MIN_VALUE
 
         fun emitResize() {
             val size = runCatching { activeTerm.size }.getOrNull() ?: return
-            val cols = size.columns
-            val rows = size.rows
-            if (cols < 1 || rows < 1) {
-                consoleFlowDebug("jline-events: ignored invalid resize columns=$cols rows=$rows")
-                return
-            }
-            val shouldEmit = synchronized(resizeEmitMutex) {
-                if (cols == lastResizeCols && rows == lastResizeRows) {
-                    false
-                } else {
-                    lastResizeCols = cols
-                    lastResizeRows = rows
-                    true
-                }
-            }
-            if (!shouldEmit) return
-            out.trySend(ConsoleEvent.Resize(cols, rows))
+            out.trySend(ConsoleEvent.Resize(size.columns, size.rows))
         }
 
         fun cleanup() {
@@ -328,13 +270,13 @@ object JvmLyngConsole : LyngConsole {
                             .onFailure { consoleFlowDebug("jline-events: reader shutdown failed during recovery", it) }
 
                         reader = activeTerm.reader()
-                        if (reader === prevReader) {
-                            consoleFlowDebug("jline-events: reader recovery no-op oldReader=${System.identityHashCode(prevReader)} newReader=${System.identityHashCode(reader)} -> forcing terminal rebuild")
+                        if (reader.hashCode() == prevReader.hashCode()) {
+                            consoleFlowDebug("jline-events: reader recovery no-op oldReader=${prevReader.hashCode()} newReader=${reader.hashCode()} -> forcing terminal rebuild")
                             if (!tryRebuildTerminal()) {
                                 consoleFlowDebug("jline-events: forced terminal rebuild did not produce a new reader")
                             }
                         } else {
-                            consoleFlowDebug("jline-events: reader recovered oldReader=${System.identityHashCode(prevReader)} newReader=${System.identityHashCode(reader)}")
+                            consoleFlowDebug("jline-events: reader recovered oldReader=${prevReader.hashCode()} newReader=${reader.hashCode()}")
                         }
 
                         readerRecoveries.incrementAndGet()
@@ -363,56 +305,18 @@ object JvmLyngConsole : LyngConsole {
                     } else {
                         keySendFailures.incrementAndGet()
                     }
-                } catch (e: InterruptedException) {
-                    // Keep input alive if this is a transient interrupt while still running.
-                    if (!running.get() || !keyLoopRunning.get()) break
-                    recoveryRequested.set(true)
-                    consoleFlowDebug("jline-events: key-reader interrupted; scheduling reader recovery", e)
-                    Thread.interrupted()
-                    continue
-                } catch (e: InterruptedIOException) {
-                    // Common during reader shutdown/rebind. Recover silently and keep input flowing.
-                    if (!running.get() || !keyLoopRunning.get()) break
-                    recoveryRequested.set(true)
-                    consoleFlowDebug("jline-events: read interrupted; scheduling reader recovery", e)
-                    try {
-                        Thread.sleep(10)
-                    } catch (ie: InterruptedException) {
-                        if (!running.get() || !keyLoopRunning.get()) break
-                        recoveryRequested.set(true)
-                        consoleFlowDebug("jline-events: interrupted during recovery backoff; continuing", ie)
-                        Thread.interrupted()
-                    }
-                } catch (e: EOFException) {
-                    // EOF from reader should trigger rebind/rebuild rather than ending input stream.
-                    if (!running.get() || !keyLoopRunning.get()) break
-                    recoveryRequested.set(true)
-                    consoleFlowDebug("jline-events: reader EOF; scheduling reader recovery", e)
-                    try {
-                        Thread.sleep(20)
-                    } catch (ie: InterruptedException) {
-                        if (!running.get() || !keyLoopRunning.get()) break
-                        recoveryRequested.set(true)
-                        consoleFlowDebug("jline-events: interrupted during EOF backoff; continuing", ie)
-                        Thread.interrupted()
-                    }
+                } catch (_: InterruptedException) {
+                    break
                 } catch (e: Throwable) {
                     readFailures.incrementAndGet()
-                    recoveryRequested.set(true)
                     consoleFlowDebug("jline-events: blocking read failed", e)
                     try {
                         Thread.sleep(50)
-                    } catch (ie: InterruptedException) {
-                        if (!running.get() || !keyLoopRunning.get()) break
-                        recoveryRequested.set(true)
-                        consoleFlowDebug("jline-events: interrupted during error backoff; continuing", ie)
-                        Thread.interrupted()
+                    } catch (_: InterruptedException) {
+                        break
                     }
                 }
             }
-            consoleFlowDebug(
-                "jline-events: key-reader thread stopped running=${running.get()} keyLoopRunning=${keyLoopRunning.get()} loops=${keyLoopCount.get()} keys=${keyEvents.get()} readFailures=${readFailures.get()}"
-            )
         }
 
         heartbeatThread = thread(start = true, isDaemon = true, name = "lyng-jline-heartbeat") {
@@ -430,17 +334,11 @@ object JvmLyngConsole : LyngConsole {
                     val readBlockedMs = if (readStartNs > 0L && readEndNs < readStartNs) {
                         (System.nanoTime() - readStartNs) / 1_000_000L
                     } else 0L
-                    val streamIdle = requested && keyCodesRead.get() > 0L && idleMs >= 1400L
-                    val readStalled = requested && readBlockedMs >= 1600L
-                    if (streamIdle || readStalled) {
+                    if (requested && keyCodesRead.get() > 0L && idleMs >= 1400L) {
                         val sinceRecoveryMs = (System.nanoTime() - lastRecoveryNs.get()) / 1_000_000L
                         if (sinceRecoveryMs >= 1200L) {
                             recoveryRequested.set(true)
-                            if (readStalled) {
-                                consoleFlowDebug("jline-events: key read blocked ${readBlockedMs}ms; scheduling reader recovery")
-                            } else {
-                                consoleFlowDebug("jline-events: key stream idle ${idleMs}ms; scheduling reader recovery")
-                            }
+                            consoleFlowDebug("jline-events: key stream idle ${idleMs}ms; scheduling reader recovery")
                         }
                     }
                     consoleFlowDebug(
@@ -468,7 +366,6 @@ object JvmLyngConsole : LyngConsole {
             }
 
             override suspend fun close() {
-                consoleFlowDebug("jline-events: collector close requested", Throwable("collector close caller"))
                 cleanup()
                 consoleFlowDebug(
                     "jline-events: collector ended keys=${keyEvents.get()} readFailures=${readFailures.get()}"
@@ -588,15 +485,12 @@ object JvmLyngConsole : LyngConsole {
         ctrl: Boolean = false,
         alt: Boolean = false,
         shift: Boolean = false,
-    ): ConsoleEvent.KeyDown {
-        require(value.isNotEmpty()) { "ConsoleEvent.KeyDown.key must never be empty" }
-        return ConsoleEvent.KeyDown(
-            key = value,
-            code = null,
-            ctrl = ctrl,
-            alt = alt,
-            shift = shift,
-            meta = false
-        )
-    }
+    ): ConsoleEvent.KeyDown = ConsoleEvent.KeyDown(
+        key = value,
+        code = null,
+        ctrl = ctrl,
+        alt = alt,
+        shift = shift,
+        meta = false
+    )
 }

lyngio/src/jvmTest/kotlin/net/sergeych/lyng/io/console/LyngConsoleModuleTest.kt

@@ -56,7 +56,7 @@ class LyngConsoleModuleTest {
             val d = Console.details()
             assert(d.supported is Bool)
             assert(d.isTty is Bool)
-            assert(d.ansiLevel is ConsoleAnsiLevel)
+            assert(d.ansiLevel is String)
 
             val g = Console.geometry()
             if (g != null) {

lyngio/stdlib/lyng/io/console.lyng

@@ -1,157 +0,0 @@
-package lyng.io.console
-
-/* Console event kinds used by `ConsoleEvent.type`. */
-enum ConsoleEventType {
-    UNKNOWN,
-    RESIZE,
-    KEY_DOWN,
-    KEY_UP
-}
-
-/* Normalized key codes used by `ConsoleKeyEvent.code`. */
-enum ConsoleKeyCode {
-    UNKNOWN,
-    CHARACTER,
-    ARROW_UP,
-    ARROW_DOWN,
-    ARROW_LEFT,
-    ARROW_RIGHT,
-    HOME,
-    END,
-    INSERT,
-    DELETE,
-    PAGE_UP,
-    PAGE_DOWN,
-    ESCAPE,
-    ENTER,
-    TAB,
-    BACKSPACE,
-    SPACE
-}
-
-/* Detected ANSI terminal capability level. */
-enum ConsoleAnsiLevel {
-    NONE,
-    BASIC16,
-    ANSI256,
-    TRUECOLOR
-}
-
-/* Base class for console events. */
-extern class ConsoleEvent {
-    /* Event kind for stable matching/switching. */
-    val type: ConsoleEventType
-}
-
-/* Terminal resize event. */
-extern class ConsoleResizeEvent : ConsoleEvent {
-    /* Current terminal width in character cells. */
-    val columns: Int
-    /* Current terminal height in character cells. */
-    val rows: Int
-}
-
-/* Keyboard event. */
-extern class ConsoleKeyEvent : ConsoleEvent {
-    /*
-        Logical key name normalized for app-level handling, for example:
-        "a", "A", "ArrowLeft", "Escape", "Enter".
-    */
-    val key: String
-    /* Normalized key code enum for robust matching independent of backend specifics. */
-    val code: ConsoleKeyCode
-    /*
-        Optional backend-specific raw identifier (if available).
-        Not guaranteed to be present or stable across platforms.
-    */
-    val codeName: String?
-    /* True when Ctrl was pressed during the key event. */
-    val ctrl: Bool
-    /* True when Alt/Option was pressed during the key event. */
-    val alt: Bool
-    /* True when Shift was pressed during the key event. */
-    val shift: Bool
-    /* True when Meta/Super/Command was pressed during the key event. */
-    val meta: Bool
-}
-
-/* Pull iterator over console events. */
-extern class ConsoleEventIterator : Iterator<ConsoleEvent> {
-    /* Whether another event is currently available from the stream. */
-    override fun hasNext(): Bool
-    /* Returns next event or throws iteration-finished when exhausted/cancelled. */
-    override fun next(): ConsoleEvent
-    /* Stops this iterator. The underlying console service remains managed by runtime. */
-    override fun cancelIteration(): void
-}
-
-/* Endless iterable console event stream. */
-extern class ConsoleEventStream : Iterable<ConsoleEvent> {
-    /* Creates a fresh event iterator bound to the current console input stream. */
-    override fun iterator(): ConsoleEventIterator
-}
-
-/* Terminal geometry in character cells. */
-extern class ConsoleGeometry {
-    val columns: Int
-    val rows: Int
-}
-
-/* Snapshot of console support/capabilities. */
-extern class ConsoleDetails {
-    /* True when current runtime has console control implementation. */
-    val supported: Bool
-    /* True when output/input are attached to an interactive terminal. */
-    val isTty: Bool
-    /* Detected terminal color capability level. */
-    val ansiLevel: ConsoleAnsiLevel
-    /* Current terminal size if available, otherwise null. */
-    val geometry: ConsoleGeometry?
-}
-
-/* Console API singleton object. */
-extern object Console {
-    /* Returns true when console control API is implemented in this runtime. */
-    fun isSupported(): Bool
-    /* Returns true when process is attached to interactive TTY. */
-    fun isTty(): Bool
-    /* Returns detected color capability level. */
-    fun ansiLevel(): ConsoleAnsiLevel
-    /* Returns current terminal geometry, or null when unavailable. */
-    fun geometry(): ConsoleGeometry?
-    /* Returns combined capability snapshot in one call. */
-    fun details(): ConsoleDetails
-
-    /* Writes raw text to console output buffer (no implicit newline). */
-    fun write(text: String): void
-    /* Flushes pending console output. Call after batched writes. */
-    fun flush(): void
-
-    /* Moves cursor to home position (row 1, column 1). */
-    fun home(): void
-    /* Clears visible screen buffer. Cursor position is backend-dependent after clear. */
-    fun clear(): void
-    /* Moves cursor to 1-based row/column. Values outside viewport are backend-defined. */
-    fun moveTo(row: Int, column: Int): void
-    /* Clears current line content. Cursor stays on the same line. */
-    fun clearLine(): void
-
-    /* Switches terminal into alternate screen buffer (useful for TUIs). */
-    fun enterAltScreen(): void
-    /* Returns from alternate screen buffer to the normal terminal screen. */
-    fun leaveAltScreen(): void
-    /* Shows or hides the cursor. Prefer restoring visibility in finally blocks. */
-    fun setCursorVisible(visible: Bool): void
-
-    /*
-        Returns endless event stream (resize + key events).
-        Typical usage is consuming in a launched loop.
-    */
-    fun events(): ConsoleEventStream
-
-    /*
-        Enables/disables raw keyboard mode.
-        Returns true when state was actually changed.
-    */
-    fun setRawMode(enabled: Bool): Bool
-}

lynglib/build.gradle.kts

@@ -21,7 +21,7 @@ import org.jetbrains.kotlin.gradle.ExperimentalWasmDsl
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 group = "net.sergeych"
-version = "1.5.0"
+version = "1.5.0-RC"
 
 // Removed legacy buildscript classpath declarations; plugins are applied via the plugins DSL below
 

lynglib/stdlib/lyng/root.lyng

@@ -81,7 +81,6 @@ extern fun abs(x: Object): Real
 extern fun ln(x: Object): Real
 extern fun pow(x: Object, y: Object): Real
 extern fun sqrt(x: Object): Real
-extern fun clamp<T>(value: T, range: Range<T>): T
 
 class SeededRandom {
     extern fun nextInt(): Int

site/src/jsMain/resources/index.html

@@ -339,7 +339,7 @@
 <!-- Top-left version ribbon -->
 <div class="corner-ribbon bg-danger text-white">
         <span style="margin-left: -5em">
-            v1.5.0
+            v1.5.0-RC
         </span>
 </div>
 <!-- Fixed top navbar for the whole site -->