28 files changed, 1211 insertions, 475 deletions

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 093ef05..5b3d31a 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -21,7 +21,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ['ubuntu-20.04', 'macos-13']
+        os: ['ubuntu-24.04', 'macos-13']
         luaVersion:
           - "5.1"
           - "5.2"
@@ -97,7 +97,7 @@ jobs:
 
       - uses: hishamhm/gh-actions-luarocks@master
         with:
-          luaRocksVersion: "3.11.0"
+          luaRocksVersion: "3.12.0"
 
       - name: test dependencies
         run: |
diff --git a/.github/workflows/luacheck.yml b/.github/workflows/lint.yml
index 3ad8db7..83abc44 100644
--- a/.github/workflows/luacheck.yml
+++ b/.github/workflows/lint.yml
@@ -1,5 +1,5 @@
 ---
-name: Luacheck
+name: Lint
 
 on: [push, pull_request]
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c9e15e..3b00fb6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,33 @@ The scope of what is covered by the version number excludes:
 
 ## Version history
 
+### version 0.6.3, released 11-Jul-2025
+
+- Fix: maximum key-delay, reduced from 0.2 to 0.1 seconds to reduce slugginess feel on some key presses.
+  See [#69](https://github.com/lunarmodules/luasystem/pull/69).
+- Fix: `readansi` now only reports printable chars as characters
+  See [#70](https://github.com/lunarmodules/luasystem/pull/70).
+- Fix: readkey now ignores Windows scancodes if received.
+  See [#74](https://github.com/lunarmodules/luasystem/pull/74).
+- Fix: readkey now passes errors on.
+  See [#74](https://github.com/lunarmodules/luasystem/pull/74).
+
+### version 0.6.2, released 15-Apr-2025
+
+- Fix: autotermrestore didn't work because its metatable was overwritten.
+
+### version 0.6.1, released 13-Apr-2025
+
+- Docs: document readansi internal buffer for incomplete sequences.
+- Fix: ensure to properly parse `<alt>+key` key presses
+
+### version 0.6.0, released 10-Apr-2025
+
+- Fix: when sleep returns an error, pass that on in `readkey`.
+- Feat: added `detachfds` which will create separate file descriptions for `stdout`
+  and `stderr` to ensure that related settings (eg. non-blocking flag) will not be shared
+  amongst those streams and `stdin`.
+
 ### version 0.5.1, released 12-Mar-2025
 
 - Fix: on older unixes with glibc < 2.25, fall back to `/dev/urandom`
@@ -38,12 +65,12 @@ The scope of what is covered by the version number excludes:
 - Feat: allow passing in a sleep function to `readkey` and `readansi`
 - Fix: NetBSD fix compilation, undeclared directives
 - Refactor: random bytes; remove deprecated API usage on Windows, move to
-  binary api instead of /dev/urandom file on linux and bsd
+  binary api instead of `/dev/urandom` file on linux and bsd
 
 ### version 0.4.5, released 18-Dec-2024
 
 - Fix: suppress a warning when building with clang
-- Fix: do not rely on luaconf.h to include limits.h, fixes builds with latest LuaJIT (#38).
+- Fix: do not rely on `luaconf.h` to include `limits.h`, fixes builds with latest LuaJIT (#38).
 
 ### version 0.4.4, released 03-Sep-2024
 
diff --git a/doc_topics/03-terminal.md b/doc_topics/03-terminal.md
index 5bdf543..a5341d6 100644
--- a/doc_topics/03-terminal.md
+++ b/doc_topics/03-terminal.md
@@ -16,6 +16,7 @@ Since there are a myriad of settings available;
 - `system.setconsoleflags` (Windows)
 - `system.setconsolecp` (Windows)
 - `system.setconsoleoutputcp` (Windows)
+- `system.detachfds` (Posix)
 - `system.setnonblock` (Posix)
 - `system.tcsetattr` (Posix)
 
@@ -105,6 +106,7 @@ To use non-blocking input here's how to set it up:
     sys.setconsoleflags(io.stdin, sys.getconsoleflags(io.stdin) - sys.CIF_ECHO_INPUT - sys.CIF_LINE_INPUT)
 
     -- setup Posix by disabling echo, canonical mode, and making non-blocking
+    sys.detachfds()  -- ensure stdin/out/err have their own file descriptions
     local of_attr = sys.tcgetattr(io.stdin)
     sys.tcsetattr(io.stdin, sys.TCSANOW, {
       lflag = of_attr.lflag - sys.L_ICANON - sys.L_ECHO,
diff --git a/docs/classes/bitflags.html b/docs/classes/bitflags.html
index 647cc62..7637aeb 100644
--- a/docs/classes/bitflags.html
+++ b/docs/classes/bitflags.html
@@ -298,7 +298,7 @@ return <code>false</code> if the flags are checked.
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/compat.lua.html b/docs/examples/compat.lua.html
index e421044..ca4e489 100644
--- a/docs/examples/compat.lua.html
+++ b/docs/examples/compat.lua.html
@@ -112,7 +112,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/flag_debugging.lua.html b/docs/examples/flag_debugging.lua.html
index e8a75e3..dba4471 100644
--- a/docs/examples/flag_debugging.lua.html
+++ b/docs/examples/flag_debugging.lua.html
@@ -80,7 +80,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/password_input.lua.html b/docs/examples/password_input.lua.html
index a5eac4d..342b066 100644
--- a/docs/examples/password_input.lua.html
+++ b/docs/examples/password_input.lua.html
@@ -132,7 +132,7 @@ useful for reading secrets from the user.
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/read.lua.html b/docs/examples/read.lua.html
index 3b53a8b..4995bda 100644
--- a/docs/examples/read.lua.html
+++ b/docs/examples/read.lua.html
@@ -143,7 +143,7 @@ sys.<span class="function-name">setnonblock</span>(<span class="global">io</span
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/readline.lua.html b/docs/examples/readline.lua.html
index dd63721..493de2c 100644
--- a/docs/examples/readline.lua.html
+++ b/docs/examples/readline.lua.html
@@ -549,7 +549,7 @@ sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/spinner.lua.html b/docs/examples/spinner.lua.html
index 99a1c91..6e2d63a 100644
--- a/docs/examples/spinner.lua.html
+++ b/docs/examples/spinner.lua.html
@@ -137,7 +137,7 @@ sys.<span class="function-name">setnonblock</span>(<span class="global">io</span
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/spiral_snake.lua.html b/docs/examples/spiral_snake.lua.html
index 7be16e8..97d5f77 100644
--- a/docs/examples/spiral_snake.lua.html
+++ b/docs/examples/spiral_snake.lua.html
@@ -145,7 +145,7 @@ codes for moving the cursor around.
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/examples/terminalsize.lua.html b/docs/examples/terminalsize.lua.html
index 6a6a93e..d3486bb 100644
--- a/docs/examples/terminalsize.lua.html
+++ b/docs/examples/terminalsize.lua.html
@@ -110,7 +110,7 @@ sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/index.html b/docs/index.html
index 5d7b02f..e901d08 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -142,7 +142,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/modules/system.html b/docs/modules/system.html
index fa41458..0a2447e 100644
--- a/docs/modules/system.html
+++ b/docs/modules/system.html
@@ -37,7 +37,12 @@
 <li><a href="#Environment">Environment </a></li>
 <li><a href="#Random">Random </a></li>
 <li><a href="#Terminal">Terminal </a></li>
+<li><a href="#Terminal_Windows">Terminal_Windows</a></li>
+<li><a href="#Terminal_Posix">Terminal_Posix</a></li>
+<li><a href="#Terminal_Input">Terminal_Input</a></li>
+<li><a href="#Terminal_UTF_8">Terminal_UTF-8</a></li>
 <li><a href="#Time">Time </a></li>
+<li><a href="#Terminal_Backup">Terminal_Backup</a></li>
 </ul>
 
 
@@ -112,93 +117,93 @@
 <h2><a href="#Terminal">Terminal </a></h2>
 <table class="function_list">
         <tr>
-        <td class="name" nowrap><a href="#CODEPAGE_UTF8">CODEPAGE_UTF8</a></td>
-        <td class="summary">UTF8 codepage.</td>
-        </tr>
-        <tr>
-        <td class="name" nowrap><a href="#_readkey">_readkey ()</a></td>
-        <td class="summary">Reads a key from the console non-blocking.</td>
-        </tr>
-        <tr>
-        <td class="name" nowrap><a href="#autotermrestore">autotermrestore ()</a></td>
-        <td class="summary">Backs up terminal settings and restores them on application exit.</td>
+        <td class="name" nowrap><a href="#isatty">isatty (file)</a></td>
+        <td class="summary">Checks if a file-handle is a TTY.</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#getconsolecp">getconsolecp ()</a></td>
-        <td class="summary">Gets the current console code page (Windows).</td>
+        <td class="name" nowrap><a href="#termsize">termsize ()</a></td>
+        <td class="summary">Get the size of the terminal in rows and columns.</td>
         </tr>
+</table>
+<h2><a href="#Terminal_Windows">Terminal_Windows</a></h2>
+<table class="function_list">
         <tr>
         <td class="name" nowrap><a href="#getconsoleflags">getconsoleflags (file)</a></td>
         <td class="summary">Gets console flags (Windows).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#getconsoleoutputcp">getconsoleoutputcp ()</a></td>
-        <td class="summary">Gets the current console output code page (Windows).</td>
+        <td class="name" nowrap><a href="#listconsoleflags">listconsoleflags (fh)</a></td>
+        <td class="summary">Debug function for console flags (Windows).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#getnonblock">getnonblock (fd)</a></td>
-        <td class="summary">Gets non-blocking mode status for a file (Posix).</td>
+        <td class="name" nowrap><a href="#setconsoleflags">setconsoleflags (file, bitflags)</a></td>
+        <td class="summary">Sets the console flags (Windows).</td>
         </tr>
+</table>
+<h2><a href="#Terminal_Posix">Terminal_Posix</a></h2>
+<table class="function_list">
         <tr>
-        <td class="name" nowrap><a href="#isatty">isatty (file)</a></td>
-        <td class="summary">Checks if a file-handle is a TTY.</td>
+        <td class="name" nowrap><a href="#detachfds">detachfds ()</a></td>
+        <td class="summary">Creates new file descriptions for <code>stdout</code> and <code>stderr</code>.</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#listconsoleflags">listconsoleflags (fh)</a></td>
-        <td class="summary">Debug function for console flags (Windows).</td>
+        <td class="name" nowrap><a href="#getnonblock">getnonblock (fd)</a></td>
+        <td class="summary">Gets non-blocking mode status for a file (Posix).</td>
         </tr>
         <tr>
         <td class="name" nowrap><a href="#listtermflags">listtermflags (fh)</a></td>
         <td class="summary">Debug function for terminal flags (Posix).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#readansi">readansi (timeout[, fsleep=system.sleep])</a></td>
-        <td class="summary">Reads a single key, if it is the start of ansi escape sequence then it reads
- the full sequence.</td>
-        </tr>
-        <tr>
-        <td class="name" nowrap><a href="#readkey">readkey (timeout[, fsleep=system.sleep])</a></td>
-        <td class="summary">Reads a single byte from the console, with a timeout.</td>
+        <td class="name" nowrap><a href="#setnonblock">setnonblock (fd, make_non_block)</a></td>
+        <td class="summary">Enables or disables non-blocking mode for a file (Posix).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#setconsolecp">setconsolecp (cp)</a></td>
-        <td class="summary">Sets the current console code page (Windows).</td>
+        <td class="name" nowrap><a href="#tcgetattr">tcgetattr (fd)</a></td>
+        <td class="summary">Get termios state (Posix).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#setconsoleflags">setconsoleflags (file, bitflags)</a></td>
-        <td class="summary">Sets the console flags (Windows).</td>
+        <td class="name" nowrap><a href="#tcsetattr">tcsetattr (fd, actions, termios)</a></td>
+        <td class="summary">Set termios state (Posix).</td>
         </tr>
+</table>
+<h2><a href="#Terminal_Input">Terminal_Input</a></h2>
+<table class="function_list">
         <tr>
-        <td class="name" nowrap><a href="#setconsoleoutputcp">setconsoleoutputcp (cp)</a></td>
-        <td class="summary">Sets the current console output code page (Windows).</td>
+        <td class="name" nowrap><a href="#_readkey">_readkey ()</a></td>
+        <td class="summary">Reads a key from the console non-blocking.</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#setnonblock">setnonblock (fd, make_non_block)</a></td>
-        <td class="summary">Enables or disables non-blocking mode for a file (Posix).</td>
+        <td class="name" nowrap><a href="#readansi">readansi (timeout[, fsleep=system.sleep])</a></td>
+        <td class="summary">Reads a single key, if it is the start of ansi escape sequence then it reads
+ the full sequence.</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#tcgetattr">tcgetattr (fd)</a></td>
-        <td class="summary">Get termios state (Posix).</td>
+        <td class="name" nowrap><a href="#readkey">readkey (timeout[, fsleep=system.sleep])</a></td>
+        <td class="summary">Reads a single byte from the console, with a timeout.</td>
         </tr>
+</table>
+<h2><a href="#Terminal_UTF_8">Terminal_UTF-8</a></h2>
+<table class="function_list">
         <tr>
-        <td class="name" nowrap><a href="#tcsetattr">tcsetattr (fd, actions, termios)</a></td>
-        <td class="summary">Set termios state (Posix).</td>
+        <td class="name" nowrap><a href="#CODEPAGE_UTF8">CODEPAGE_UTF8</a></td>
+        <td class="summary">UTF8 codepage.</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#termbackup">termbackup ()</a></td>
-        <td class="summary">Returns a backup of terminal settings for stdin/out/err.</td>
+        <td class="name" nowrap><a href="#getconsolecp">getconsolecp ()</a></td>
+        <td class="summary">Gets the current console code page (Windows).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#termrestore">termrestore (backup)</a></td>
-        <td class="summary">Restores terminal settings from a backup</td>
+        <td class="name" nowrap><a href="#getconsoleoutputcp">getconsoleoutputcp ()</a></td>
+        <td class="summary">Gets the current console output code page (Windows).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#termsize">termsize ()</a></td>
-        <td class="summary">Get the size of the terminal in rows and columns.</td>
+        <td class="name" nowrap><a href="#setconsolecp">setconsolecp (cp)</a></td>
+        <td class="summary">Sets the current console code page (Windows).</td>
         </tr>
         <tr>
-        <td class="name" nowrap><a href="#termwrap">termwrap (f)</a></td>
-        <td class="summary">Wraps a function to automatically restore terminal settings upon returning.</td>
+        <td class="name" nowrap><a href="#setconsoleoutputcp">setconsoleoutputcp (cp)</a></td>
+        <td class="summary">Sets the current console output code page (Windows).</td>
         </tr>
         <tr>
         <td class="name" nowrap><a href="#utf8cwidth">utf8cwidth (utf8_char)</a></td>
@@ -224,6 +229,25 @@
         <td class="summary">Sleep without a busy loop.</td>
         </tr>
 </table>
+<h2><a href="#Terminal_Backup">Terminal_Backup</a></h2>
+<table class="function_list">
+        <tr>
+        <td class="name" nowrap><a href="#autotermrestore">autotermrestore ()</a></td>
+        <td class="summary">Backs up terminal settings and restores them on application exit.</td>
+        </tr>
+        <tr>
+        <td class="name" nowrap><a href="#termbackup">termbackup ()</a></td>
+        <td class="summary">Returns a backup of terminal settings for stdin/out/err.</td>
+        </tr>
+        <tr>
+        <td class="name" nowrap><a href="#termrestore">termrestore (backup)</a></td>
+        <td class="summary">Restores terminal settings from a backup</td>
+        </tr>
+        <tr>
+        <td class="name" nowrap><a href="#termwrap">termwrap (f)</a></td>
+        <td class="summary">Wraps a function to automatically restore terminal settings upon returning.</td>
+        </tr>
+</table>
 
 <br/>
 <br/>
@@ -399,95 +423,66 @@ requested number of bytes, or an error, never a partial result.
           </div>
     <dl class="function">
     <dt>
-    <a name = "CODEPAGE_UTF8"></a>
-    <strong>CODEPAGE_UTF8</strong>
+    <a name = "isatty"></a>
+    <strong>isatty (file)</strong>
     </dt>
     <dd>
-    UTF8 codepage.
- To be used with <a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> and <a href="../modules/system.html#setconsolecp">system.setconsolecp</a>.
+    Checks if a file-handle is a TTY.
 
 
+    <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">CODEPAGE_UTF8</span>
-         The Windows CodePage for UTF8.
+        <li><span class="parameter">file</span>
+            <span class="types"><span class="type">file</span></span>
+         the file-handle to check, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>.
         </li>
     </ul>
 
-
-
-
-
-</dd>
-    <dt>
-    <a name = "_readkey"></a>
-    <strong>_readkey ()</strong>
-    </dt>
-    <dd>
-    Reads a key from the console non-blocking.  This function should not be called
-directly, but through the <a href="../modules/system.html#readkey">system.readkey</a> or <a href="../modules/system.html#readansi">system.readansi</a> functions. It
-will return the next byte from the input stream, or <code>nil</code> if no key was pressed.</p>
-
-<p>On Posix, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a> must be set to non-blocking mode using <a href="../modules/system.html#setnonblock">setnonblock</a>
-and canonical mode must be turned off using <a href="../modules/system.html#tcsetattr">tcsetattr</a>,
-before calling this function. Otherwise it will block. No conversions are
-done on Posix, so the byte read is returned as-is.</p>
-
-<p>On Windows this reads a wide character and converts it to UTF-8. Multi-byte
-sequences will be buffered internally and returned one byte at a time.
-
-
-
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><span class="type">integer</span></span>
-        the byte read from the input stream
-    </ol>
-     <h3>Or</h3>
-    <ol>
-
-           <span class="types"><span class="type">nil</span></span>
-        if no key was pressed
-    </ol>
-     <h3>Or</h3>
-    <ol>
-        <li>
-           <span class="types"><span class="type">nil</span></span>
-        on error</li>
-        <li>
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        error message</li>
-        <li>
-           <span class="types"><span class="type">int</span></span>
-        errnum (on posix)</li>
+           <span class="types"><span class="type">boolean</span></span>
+        true if the file is a tty
     </ol>
 
 
 
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
+<span class="keyword">if</span> system.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span>
+    <span class="comment">-- enable ANSI coloring etc on Windows, does nothing in Posix.
+</span>    <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
+    system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, flags + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
+<span class="keyword">end</span></pre>
+    </ul>
 
 </dd>
     <dt>
-    <a name = "autotermrestore"></a>
-    <strong>autotermrestore ()</strong>
+    <a name = "termsize"></a>
+    <strong>termsize ()</strong>
     </dt>
     <dd>
-    Backs up terminal settings and restores them on application exit.
- Calls <a href="../modules/system.html#termbackup">termbackup</a> to back up terminal settings and sets up a GC method to
- automatically restore them on application exit (also works on Lua 5.1).
+    Get the size of the terminal in rows and columns.
 
 
 
     <h3>Returns:</h3>
     <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-        true
+        <li>
+           <span class="types"><span class="type">int</span></span>
+        the number of rows</li>
+        <li>
+           <span class="types"><span class="type">int</span></span>
+        the number of columns</li>
     </ol>
      <h3>Or</h3>
     <ol>
         <li>
            <span class="types"><span class="type">nil</span></span>
-        if the backup was already created</li>
+
+
+</li>
         <li>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
         error message</li>
@@ -497,26 +492,10 @@ sequences will be buffered internally and returned one byte at a time.
 
 
 </dd>
-    <dt>
-    <a name = "getconsolecp"></a>
-    <strong>getconsolecp ()</strong>
-    </dt>
-    <dd>
-    Gets the current console code page (Windows).
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">int</span></span>
-        the current code page (always 65001 on Posix systems)
-    </ol>
-
-
-
+</dl>
+    <h2 class="section-header "><a name="Terminal_Windows"></a>Terminal_Windows</h2>
 
-</dd>
+    <dl class="function">
     <dt>
     <a name = "getconsoleflags"></a>
     <strong>getconsoleflags (file)</strong>
@@ -575,103 +554,6 @@ for more information on the flags.
 
 </dd>
     <dt>
-    <a name = "getconsoleoutputcp"></a>
-    <strong>getconsoleoutputcp ()</strong>
-    </dt>
-    <dd>
-    Gets the current console output code page (Windows).
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">int</span></span>
-        the current code page (always 65001 on Posix systems)
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "getnonblock"></a>
-    <strong>getnonblock (fd)</strong>
-    </dt>
-    <dd>
-    Gets non-blocking mode status for a file (Posix).
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">fd</span>
-            <span class="types"><span class="type">file</span></span>
-         file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">bool</span></span>
-        <code>true</code> if set to non-blocking, <code>false</code> if not. Always returns <code>false</code> on Windows.
-    </ol>
-     <h3>Or</h3>
-    <ol>
-        <li>
-           <span class="types"><span class="type">nil</span></span>
-
-
-</li>
-        <li>
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        error message</li>
-        <li>
-           <span class="types"><span class="type">int</span></span>
-        errnum</li>
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "isatty"></a>
-    <strong>isatty (file)</strong>
-    </dt>
-    <dd>
-    Checks if a file-handle is a TTY.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">file</span>
-            <span class="types"><span class="type">file</span></span>
-         the file-handle to check, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>.
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-        true if the file is a tty
-    </ol>
-
-
-
-    <h3>Usage:</h3>
-    <ul>
-        <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
-<span class="keyword">if</span> system.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span>
-    <span class="comment">-- enable ANSI coloring etc on Windows, does nothing in Posix.
-</span>    <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
-    system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, flags + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
-<span class="keyword">end</span></pre>
-    </ul>
-
-</dd>
-    <dt>
     <a name = "listconsoleflags"></a>
     <strong>listconsoleflags (fh)</strong>
     </dt>
@@ -700,192 +582,125 @@ system.<span class="function-name">listconsoleflags</span>(<span class="global">
 
 </dd>
     <dt>
-    <a name = "listtermflags"></a>
-    <strong>listtermflags (fh)</strong>
+    <a name = "setconsoleflags"></a>
+    <strong>setconsoleflags (file, bitflags)</strong>
     </dt>
     <dd>
-    Debug function for terminal flags (Posix).
- Pretty prints the current flags set for the handle.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">fh</span>
-         file handle (<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>)
-        </li>
-    </ul>
-
-
-
+    Sets the console flags (Windows).
+The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the
+input flags (for use with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>) and <code>COF</code> are the output flags (for use with
+<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>/<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>).</p>
 
-    <h3>Usage:</h3>
-    <ul>
-        <pre class="example"><span class="comment">-- Print the flags for stdin/out/err
-</span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin)
-system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout)
-system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre>
-    </ul>
+<p>To see flag status and constant names check <a href="../modules/system.html#listconsoleflags">listconsoleflags</a>.</p>
 
-</dd>
-    <dt>
-    <a name = "readansi"></a>
-    <strong>readansi (timeout[, fsleep=system.sleep])</strong>
-    </dt>
-    <dd>
-    Reads a single key, if it is the start of ansi escape sequence then it reads
- the full sequence.  The key can be a multi-byte string in case of multibyte UTF-8 character.
- This function uses <a href="../modules/system.html#readkey">system.readkey</a>, and hence <code>fsleep</code> to wait until either a key is
- available or the timeout is reached.
- It returns immediately if a key is available or if <code>timeout</code> is less than or equal to <code>0</code>.
- In case of an ANSI sequence, it will return the full sequence as a string.
+<p>Note: not all combinations of flags are allowed, as some are mutually exclusive or mutually required.
+See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a>
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">timeout</span>
-            <span class="types"><span class="type">number</span></span>
-         the timeout in seconds.
+        <li><span class="parameter">file</span>
+            <span class="types"><span class="type">file</span></span>
+         file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
         </li>
-        <li><span class="parameter">fsleep</span>
-            <span class="types"><span class="type">function</span></span>
-         the function to call for sleeping.
-         (<em>default</em> system.sleep)
+        <li><span class="parameter">bitflags</span>
+            <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
+         the flags to set/unset
         </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
-        <li>
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        the character that was received (can be multi-byte), or a complete ANSI sequence</li>
-        <li>
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        the type of input: <code>&quot;char&quot;</code> for a single key, <code>&quot;ansi&quot;</code> for an ANSI sequence</li>
+
+           <span class="types"><span class="type">boolean</span></span>
+        <code>true</code> on success
     </ol>
      <h3>Or</h3>
     <ol>
         <li>
            <span class="types"><span class="type">nil</span></span>
-        in case of an error</li>
-        <li>
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        error message; <code>&quot;timeout&quot;</code> if the timeout was reached.</li>
+
+
+</li>
         <li>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        partial result in case of an error while reading a sequence, the sequence so far.</li>
+        error message</li>
     </ol>
 
 
 
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
+system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List all the available flags and their current status
+</span>
+<span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
+<span class="global">assert</span>(system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout,
+        flags + system.COF_VIRTUAL_TERMINAL_PROCESSING)
+
+system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List again to check the differences</span></pre>
+    </ul>
 
 </dd>
+</dl>
+    <h2 class="section-header "><a name="Terminal_Posix"></a>Terminal_Posix</h2>
+
+    <dl class="function">
     <dt>
-    <a name = "readkey"></a>
-    <strong>readkey (timeout[, fsleep=system.sleep])</strong>
+    <a name = "detachfds"></a>
+    <strong>detachfds ()</strong>
     </dt>
     <dd>
-    Reads a single byte from the console, with a timeout.
- This function uses <code>fsleep</code> to wait until either a byte is available or the timeout is reached.
- The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.2 seconds.
- It returns immediately if a byte is available or if <code>timeout</code> is less than or equal to <code>0</code>.</p>
+    Creates new file descriptions for <code>stdout</code> and <code>stderr</code>.
+Even if the file descriptors are unique, they still might point to the same
+file description, and hence share settings like <code>O_NONBLOCK</code>. This means that
+if one of them is set to non-blocking, the other will be as well. This can
+lead to unexpected behavior.</p>
 
-<p> Using <a href="../modules/system.html#readansi">system.readansi</a> is preferred over this function. Since this function can leave stray/invalid
- byte-sequences in the input buffer, while <a href="../modules/system.html#readansi">system.readansi</a> reads full ANSI and UTF8 sequences.
+<p>This function is used to detach <code>stdout</code> and <code>stderr</code> from the original
+file descriptions, and create new file descriptions for them. This allows
+independent control of flags (e.g., <code>O_NONBLOCK</code>) on <code>stdout</code> and <code>stderr</code>,
+avoiding shared side effects.</p>
+
+<p>Does not modify <code>stdin</code> (fd 0), and does nothing on Windows.
 
 
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">timeout</span>
-            <span class="types"><span class="type">number</span></span>
-         the timeout in seconds.
-        </li>
-        <li><span class="parameter">fsleep</span>
-            <span class="types"><span class="type">function</span></span>
-         the function to call for sleeping.
-         (<em>default</em> system.sleep)
-        </li>
-    </ul>
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><span class="type">byte</span></span>
-        the byte value that was read.
+        boolean <code>true</code> on success, or throws an error on failure.
     </ol>
-     <h3>Or</h3>
-    <ol>
-        <li>
-           <span class="types"><span class="type">nil</span></span>
-        if no key was read</li>
-        <li>
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        error message; <code>&quot;timeout&quot;</code> if the timeout was reached.</li>
-    </ol>
-
 
 
-
-</dd>
-    <dt>
-    <a name = "setconsolecp"></a>
-    <strong>setconsolecp (cp)</strong>
-    </dt>
-    <dd>
-    Sets the current console code page (Windows).
-
-
-    <h3>Parameters:</h3>
+    <h3>See also:</h3>
     <ul>
-        <li><span class="parameter">cp</span>
-            <span class="types"><span class="type">int</span></span>
-         the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
-        </li>
+         <a href="../modules/system.html#setnonblock">setnonblock</a>
     </ul>
 
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">bool</span></span>
-        <code>true</code> on success (always <code>true</code> on Posix systems)
-    </ol>
-
-
-
 
 </dd>
     <dt>
-    <a name = "setconsoleflags"></a>
-    <strong>setconsoleflags (file, bitflags)</strong>
+    <a name = "getnonblock"></a>
+    <strong>getnonblock (fd)</strong>
     </dt>
     <dd>
-    Sets the console flags (Windows).
-The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the
-input flags (for use with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>) and <code>COF</code> are the output flags (for use with
-<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>/<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>).</p>
-
-<p>To see flag status and constant names check <a href="../modules/system.html#listconsoleflags">listconsoleflags</a>.</p>
-
-<p>Note: not all combinations of flags are allowed, as some are mutually exclusive or mutually required.
-See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a>
+    Gets non-blocking mode status for a file (Posix).
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">file</span>
+        <li><span class="parameter">fd</span>
             <span class="types"><span class="type">file</span></span>
          file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
         </li>
-        <li><span class="parameter">bitflags</span>
-            <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
-         the flags to set/unset
-        </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><span class="type">boolean</span></span>
-        <code>true</code> on success
+           <span class="types"><span class="type">bool</span></span>
+        <code>true</code> if set to non-blocking, <code>false</code> if not. Always returns <code>false</code> on Windows.
     </ol>
      <h3>Or</h3>
     <ol>
@@ -897,48 +712,45 @@ See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">s
         <li>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
         error message</li>
+        <li>
+           <span class="types"><span class="type">int</span></span>
+        errnum</li>
     </ol>
 
 
-
-    <h3>Usage:</h3>
+    <h3>See also:</h3>
     <ul>
-        <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
-system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List all the available flags and their current status
-</span>
-<span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
-<span class="global">assert</span>(system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout,
-        flags + system.COF_VIRTUAL_TERMINAL_PROCESSING)
-
-system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List again to check the differences</span></pre>
+         <a href="../modules/system.html#setnonblock">setnonblock</a>
     </ul>
 
+
 </dd>
     <dt>
-    <a name = "setconsoleoutputcp"></a>
-    <strong>setconsoleoutputcp (cp)</strong>
+    <a name = "listtermflags"></a>
+    <strong>listtermflags (fh)</strong>
     </dt>
     <dd>
-    Sets the current console output code page (Windows).
+    Debug function for terminal flags (Posix).
+ Pretty prints the current flags set for the handle.
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">cp</span>
-            <span class="types"><span class="type">int</span></span>
-         the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
+        <li><span class="parameter">fh</span>
+         file handle (<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>)
         </li>
     </ul>
 
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">bool</span></span>
-        <code>true</code> on success (always <code>true</code> on Posix systems)
-    </ol>
 
 
 
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="comment">-- Print the flags for stdin/out/err
+</span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin)
+system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout)
+system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre>
+    </ul>
 
 </dd>
     <dt>
@@ -947,6 +759,7 @@ system.<span class="function-name">listconsoleflags</span>(<span class="global">
     </dt>
     <dd>
     Enables or disables non-blocking mode for a file (Posix).
+Check <a href="../modules/system.html#detachfds">detachfds</a> in case there are shared file descriptions.
 
 
     <h3>Parameters:</h3>
@@ -985,13 +798,15 @@ system.<span class="function-name">listconsoleflags</span>(<span class="global">
 
     <h3>See also:</h3>
     <ul>
-         <a href="../modules/system.html#getnonblock">getnonblock</a>
+         <li><a href="../modules/system.html#getnonblock">getnonblock</a></li>
+         <li><a href="../modules/system.html#detachfds">detachfds</a></li>
     </ul>
 
     <h3>Usage:</h3>
     <ul>
         <pre class="example"><span class="keyword">local</span> sys = <span class="global">require</span>(<span class="string">'system'</span>)
-
+sys.<span class="function-name">detachfds</span>() <span class="comment">-- detach stdout and stderr, so only stdin becomes non-blocking
+</span>
 <span class="comment">-- set io.stdin to non-blocking mode
 </span><span class="keyword">local</span> old_setting = sys.<span class="function-name">getnonblock</span>(<span class="global">io</span>.stdin)
 sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>)
@@ -1151,21 +966,52 @@ flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code>
     </ul>
 
 </dd>
+</dl>
+    <h2 class="section-header "><a name="Terminal_Input"></a>Terminal_Input</h2>
+
+    <dl class="function">
     <dt>
-    <a name = "termbackup"></a>
-    <strong>termbackup ()</strong>
+    <a name = "_readkey"></a>
+    <strong>_readkey ()</strong>
     </dt>
     <dd>
-    Returns a backup of terminal settings for stdin/out/err.
- Handles terminal/console flags, Windows codepage, and non-block flags on the streams.
- Backs up terminal/console flags only if a stream is a tty.
+    Reads a key from the console non-blocking.  This function should not be called
+directly, but through the <a href="../modules/system.html#readkey">system.readkey</a> or <a href="../modules/system.html#readansi">system.readansi</a> functions. It
+will return the next byte from the input stream, or <code>nil</code> if no key was pressed.</p>
+
+<p>On Posix, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a> must be set to non-blocking mode using <a href="../modules/system.html#setnonblock">setnonblock</a>
+and canonical mode must be turned off using <a href="../modules/system.html#tcsetattr">tcsetattr</a>,
+before calling this function. Otherwise it will block. No conversions are
+done on Posix, so the byte read is returned as-is.</p>
+
+<p>On Windows this reads a wide character and converts it to UTF-8. Multi-byte
+sequences will be buffered internally and returned one byte at a time.
 
 
 
     <h3>Returns:</h3>
     <ol>
 
-        table with backup of terminal settings
+           <span class="types"><span class="type">integer</span></span>
+        the byte read from the input stream
+    </ol>
+     <h3>Or</h3>
+    <ol>
+
+           <span class="types"><span class="type">nil</span></span>
+        if no key was pressed
+    </ol>
+     <h3>Or</h3>
+    <ol>
+        <li>
+           <span class="types"><span class="type">nil</span></span>
+        on error</li>
+        <li>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+        error message</li>
+        <li>
+           <span class="types"><span class="type">int</span></span>
+        errnum (on posix)</li>
     </ol>
 
 
@@ -1173,60 +1019,153 @@ flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code>
 
 </dd>
     <dt>
-    <a name = "termrestore"></a>
-    <strong>termrestore (backup)</strong>
+    <a name = "readansi"></a>
+    <strong>readansi (timeout[, fsleep=system.sleep])</strong>
     </dt>
     <dd>
-    Restores terminal settings from a backup
+    Reads a single key, if it is the start of ansi escape sequence then it reads
+ the full sequence.  The key can be a multi-byte string in case of multibyte UTF-8 character.
+ This function uses <a href="../modules/system.html#readkey">system.readkey</a>, and hence <code>fsleep</code> to wait until either a key is
+ available or the timeout is reached.
+ It returns immediately if a key is available or if <code>timeout</code> is less than or equal to <code>0</code>.
+ In case of an ANSI sequence, it will return the full sequence as a string.
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">backup</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
-         the backup of terminal settings, see <a href="../modules/system.html#termbackup">termbackup</a>.
+        <li><span class="parameter">timeout</span>
+            <span class="types"><span class="type">number</span></span>
+         the timeout in seconds.
+        </li>
+        <li><span class="parameter">fsleep</span>
+            <span class="types"><span class="type">function</span></span>
+         the function to call for sleeping.
+         (<em>default</em> system.sleep)
         </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-        true
+        <li>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+        the character that was received (can be multi-byte), or a complete ANSI sequence</li>
+        <li>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+        the type of input: <code>&quot;ctrl&quot;</code> for 0-31 and 127 bytes, <code>&quot;char&quot;</code> for other UTF-8 characters, <code>&quot;ansi&quot;</code> for an ANSI sequence</li>
+    </ol>
+     <h3>Or</h3>
+    <ol>
+        <li>
+           <span class="types"><span class="type">nil</span></span>
+        in case of an error</li>
+        <li>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+        error message; <code>&quot;timeout&quot;</code> if the timeout was reached.</li>
+        <li>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         partial result in case of an error while reading a sequence, the sequence so far.
+ The function retains its own internal buffer, so on the next call the incomplete buffer is used to
+ complete the sequence.</li>
     </ol>
 
 
 
+    <h3>Usage:</h3>
+    <ul>
+        <pre class="example"><span class="keyword">local</span> key, keytype = system.<span class="function-name">readansi</span>(<span class="number">5</span>)
+<span class="keyword">if</span> keytype == <span class="string">"char"</span> <span class="keyword">then</span> ... <span class="keyword">end</span> <span class="comment">-- printable character
+</span><span class="keyword">if</span> keytype ~= <span class="string">"char"</span> <span class="keyword">then</span> ... <span class="keyword">end</span> <span class="comment">-- non-printable character or sequence
+</span><span class="keyword">if</span> keytype == <span class="string">"ansi"</span> <span class="keyword">then</span> ... <span class="keyword">end</span> <span class="comment">-- a multi-byte sequence, but not a UTF8 character
+</span><span class="keyword">if</span> keytype ~= <span class="string">"ansi"</span> <span class="keyword">then</span> ... <span class="keyword">end</span> <span class="comment">-- a valid UTF8 character (which includes control characters)
+</span><span class="keyword">if</span> keytype == <span class="string">"ctrl"</span> <span class="keyword">then</span> ... <span class="keyword">end</span> <span class="comment">-- a single-byte ctrl character (0-31, 127)</span></pre>
+    </ul>
 
 </dd>
     <dt>
-    <a name = "termsize"></a>
-    <strong>termsize ()</strong>
+    <a name = "readkey"></a>
+    <strong>readkey (timeout[, fsleep=system.sleep])</strong>
     </dt>
     <dd>
-    Get the size of the terminal in rows and columns.
+    Reads a single byte from the console, with a timeout.
+ This function uses <code>fsleep</code> to wait until either a byte is available or the timeout is reached.
+ The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.1 seconds.
+ It returns immediately if a byte is available or if <code>timeout</code> is less than or equal to <code>0</code>.</p>
 
+<p> Using <a href="../modules/system.html#readansi">system.readansi</a> is preferred over this function. Since this function can leave stray/invalid
+ byte-sequences in the input buffer, while <a href="../modules/system.html#readansi">system.readansi</a> reads full ANSI and UTF8 sequences.
 
 
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">timeout</span>
+            <span class="types"><span class="type">number</span></span>
+         the timeout in seconds.
+        </li>
+        <li><span class="parameter">fsleep</span>
+            <span class="types"><span class="type">function</span></span>
+         the function to call for sleeping; <code>ok, err = fsleep(secs)</code>
+         (<em>default</em> system.sleep)
+        </li>
+    </ul>
+
     <h3>Returns:</h3>
     <ol>
-        <li>
-           <span class="types"><span class="type">int</span></span>
-        the number of rows</li>
-        <li>
-           <span class="types"><span class="type">int</span></span>
-        the number of columns</li>
+
+           <span class="types"><span class="type">byte</span></span>
+        the byte value that was read.
     </ol>
      <h3>Or</h3>
     <ol>
         <li>
            <span class="types"><span class="type">nil</span></span>
-
-
-</li>
+        if no key was read</li>
         <li>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
-        error message</li>
+        error message when the timeout was reached (<code>&quot;timeout&quot;</code>), or if <a href="../modules/system.html#sleep">sleep</a> failed.</li>
+    </ol>
+
+
+
+
+</dd>
+</dl>
+    <h2 class="section-header "><a name="Terminal_UTF_8"></a>Terminal_UTF-8</h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "CODEPAGE_UTF8"></a>
+    <strong>CODEPAGE_UTF8</strong>
+    </dt>
+    <dd>
+    UTF8 codepage.
+ To be used with <a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> and <a href="../modules/system.html#setconsolecp">system.setconsolecp</a>.
+
+
+    <ul>
+        <li><span class="parameter">CODEPAGE_UTF8</span>
+         The Windows CodePage for UTF8.
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "getconsolecp"></a>
+    <strong>getconsolecp ()</strong>
+    </dt>
+    <dd>
+    Gets the current console code page (Windows).
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">int</span></span>
+        the current code page (always 65001 on Posix systems)
     </ol>
 
 
@@ -1234,27 +1173,73 @@ flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code>
 
 </dd>
     <dt>
-    <a name = "termwrap"></a>
-    <strong>termwrap (f)</strong>
+    <a name = "getconsoleoutputcp"></a>
+    <strong>getconsoleoutputcp ()</strong>
     </dt>
     <dd>
-    Wraps a function to automatically restore terminal settings upon returning.
- Calls <a href="../modules/system.html#termbackup">termbackup</a> before calling the function and <a href="../modules/system.html#termrestore">termrestore</a> after.
+    Gets the current console output code page (Windows).
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">int</span></span>
+        the current code page (always 65001 on Posix systems)
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "setconsolecp"></a>
+    <strong>setconsolecp (cp)</strong>
+    </dt>
+    <dd>
+    Sets the current console code page (Windows).
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">f</span>
-            <span class="types"><span class="type">function</span></span>
-         function to wrap
+        <li><span class="parameter">cp</span>
+            <span class="types"><span class="type">int</span></span>
+         the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
         </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><span class="type">function</span></span>
-        wrapped function
+           <span class="types"><span class="type">bool</span></span>
+        <code>true</code> on success (always <code>true</code> on Posix systems)
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "setconsoleoutputcp"></a>
+    <strong>setconsoleoutputcp (cp)</strong>
+    </dt>
+    <dd>
+    Sets the current console output code page (Windows).
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">cp</span>
+            <span class="types"><span class="type">int</span></span>
+         the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">bool</span></span>
+        <code>true</code> on success (always <code>true</code> on Posix systems)
     </ol>
 
 
@@ -1416,13 +1401,124 @@ This function will sleep, without doing a busy-loop and wasting CPU cycles.
 
 </dd>
 </dl>
+    <h2 class="section-header "><a name="Terminal_Backup"></a>Terminal_Backup</h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "autotermrestore"></a>
+    <strong>autotermrestore ()</strong>
+    </dt>
+    <dd>
+    Backs up terminal settings and restores them on application exit.
+ Calls <a href="../modules/system.html#termbackup">termbackup</a> to back up terminal settings and sets up a GC method to
+ automatically restore them on application exit (also works on Lua 5.1).
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+        true
+    </ol>
+     <h3>Or</h3>
+    <ol>
+        <li>
+           <span class="types"><span class="type">nil</span></span>
+        if the backup was already created</li>
+        <li>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+        error message</li>
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "termbackup"></a>
+    <strong>termbackup ()</strong>
+    </dt>
+    <dd>
+    Returns a backup of terminal settings for stdin/out/err.
+ Handles terminal/console flags, Windows codepage, and non-block flags on the streams.
+ Backs up terminal/console flags only if a stream is a tty.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+        table with backup of terminal settings
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "termrestore"></a>
+    <strong>termrestore (backup)</strong>
+    </dt>
+    <dd>
+    Restores terminal settings from a backup
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">backup</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         the backup of terminal settings, see <a href="../modules/system.html#termbackup">termbackup</a>.
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+        true
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "termwrap"></a>
+    <strong>termwrap (f)</strong>
+    </dt>
+    <dd>
+    Wraps a function to automatically restore terminal settings upon returning.
+ Calls <a href="../modules/system.html#termbackup">termbackup</a> before calling the function and <a href="../modules/system.html#termrestore">termrestore</a> after.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">f</span>
+            <span class="types"><span class="type">function</span></span>
+         function to wrap
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">function</span></span>
+        wrapped function
+    </ol>
+
+
+
+
+</dd>
+</dl>
 
 
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/topics/01-introduction.md.html b/docs/topics/01-introduction.md.html
index f0f627d..264aa71 100644
--- a/docs/topics/01-introduction.md.html
+++ b/docs/topics/01-introduction.md.html
@@ -84,7 +84,7 @@ independence.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/topics/02-development.md.html b/docs/topics/02-development.md.html
index 315fa37..15efe55 100644
--- a/docs/topics/02-development.md.html
+++ b/docs/topics/02-development.md.html
@@ -84,7 +84,7 @@ pass locally, and do not rely on CI only.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/topics/03-terminal.md.html b/docs/topics/03-terminal.md.html
index 7ce28af..27772ac 100644
--- a/docs/topics/03-terminal.md.html
+++ b/docs/topics/03-terminal.md.html
@@ -93,6 +93,7 @@ up both platforms to make it work.</p>
     <li><a href="../modules/system.html#setconsoleflags">system.setconsoleflags</a> (Windows)</li>
     <li><a href="../modules/system.html#setconsolecp">system.setconsolecp</a> (Windows)</li>
     <li><a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> (Windows)</li>
+    <li><a href="../modules/system.html#detachfds">system.detachfds</a> (Posix)</li>
     <li><a href="../modules/system.html#setnonblock">system.setnonblock</a> (Posix)</li>
     <li><a href="../modules/system.html#tcsetattr">system.tcsetattr</a> (Posix)</li>
 </ul>
@@ -195,6 +196,7 @@ also not being echoed to the terminal (independent of the echo settings used wit
 </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) - sys.CIF_ECHO_INPUT - sys.CIF_LINE_INPUT)
 
 <span class="comment">-- setup Posix by disabling echo, canonical mode, and making non-blocking
+</span>sys.<span class="function-name">detachfds</span>()  <span class="comment">-- ensure stdin/out/err have their own file descriptions
 </span><span class="keyword">local</span> of_attr = sys.<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin)
 sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, {
   lflag = of_attr.lflag - sys.L_ICANON - sys.L_ECHO,
@@ -218,7 +220,7 @@ For an example see <a href="../examples/password_input.lua.html"><code>examples/
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/topics/CHANGELOG.md.html b/docs/topics/CHANGELOG.md.html
index fa2d706..9603abd 100644
--- a/docs/topics/CHANGELOG.md.html
+++ b/docs/topics/CHANGELOG.md.html
@@ -106,6 +106,41 @@
 <p><a name="Version_history"></a></p>
 <h2>Version history</h2>
 
+<h3>version 0.6.3, released 11-Jul-2025</h3>
+
+<ul>
+    <li>Fix: maximum key-delay, reduced from 0.2 to 0.1 seconds to reduce slugginess feel on some key presses.
+    See <a href="https://github.com/lunarmodules/luasystem/pull/69">#69</a>.</li>
+    <li>Fix: <code>readansi</code> now only reports printable chars as characters
+    See <a href="https://github.com/lunarmodules/luasystem/pull/70">#70</a>.</li>
+    <li>Fix: readkey now ignores Windows scancodes if received.
+    See <a href="https://github.com/lunarmodules/luasystem/pull/74">#74</a>.</li>
+    <li>Fix: readkey now passes errors on.
+    See <a href="https://github.com/lunarmodules/luasystem/pull/74">#74</a>.</li>
+</ul>
+
+<h3>version 0.6.2, released 15-Apr-2025</h3>
+
+<ul>
+    <li>Fix: autotermrestore didn't work because its metatable was overwritten.</li>
+</ul>
+
+<h3>version 0.6.1, released 13-Apr-2025</h3>
+
+<ul>
+    <li>Docs: document readansi internal buffer for incomplete sequences.</li>
+    <li>Fix: ensure to properly parse <code>&lt;alt&gt;+key</code> key presses</li>
+</ul>
+
+<h3>version 0.6.0, released 10-Apr-2025</h3>
+
+<ul>
+    <li>Fix: when sleep returns an error, pass that on in <code>readkey</code>.</li>
+    <li>Feat: added <code>detachfds</code> which will create separate file descriptions for <code>stdout</code>
+    and <code>stderr</code> to ensure that related settings (eg. non-blocking flag) will not be shared
+    amongst those streams and <code>stdin</code>.</li>
+</ul>
+
 <h3>version 0.5.1, released 12-Mar-2025</h3>
 
 <ul>
@@ -120,14 +155,14 @@
     <li>Feat: allow passing in a sleep function to <code>readkey</code> and <code>readansi</code></li>
     <li>Fix: NetBSD fix compilation, undeclared directives</li>
     <li>Refactor: random bytes; remove deprecated API usage on Windows, move to
-    binary api instead of /dev/urandom file on linux and bsd</li>
+    binary api instead of <code>/dev/urandom</code> file on linux and bsd</li>
 </ul>
 
 <h3>version 0.4.5, released 18-Dec-2024</h3>
 
 <ul>
     <li>Fix: suppress a warning when building with clang</li>
-    <li>Fix: do not rely on luaconf.h to include limits.h, fixes builds with latest LuaJIT (#38).</li>
+    <li>Fix: do not rely on <code>luaconf.h</code> to include <code>limits.h</code>, fixes builds with latest LuaJIT (#38).</li>
 </ul>
 
 <h3>version 0.4.4, released 03-Sep-2024</h3>
@@ -199,7 +234,7 @@
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/docs/topics/LICENSE.md.html b/docs/topics/LICENSE.md.html
index 612cdb9..c0b9b93 100644
--- a/docs/topics/LICENSE.md.html
+++ b/docs/topics/LICENSE.md.html
@@ -94,7 +94,7 @@ SOFTWARE.</p>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
-<i style="float:right;">Last updated 2025-03-12 15:17:50 </i>
+<i style="float:right;">Last updated 2025-07-11 22:55:05 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>
diff --git a/rockspecs/luasystem-0.6.0-1.rockspec b/rockspecs/luasystem-0.6.0-1.rockspec
new file mode 100644
index 0000000..21c2dc0
--- /dev/null
+++ b/rockspecs/luasystem-0.6.0-1.rockspec
@@ -0,0 +1,85 @@
+local package_name = "luasystem"
+local package_version = "0.6.0"
+local rockspec_revision = "1"
+local github_account_name = "lunarmodules"
+local github_repo_name = "luasystem"
+
+
+package = package_name
+version = package_version.."-"..rockspec_revision
+
+source = {
+  url = "git+https://github.com/"..github_account_name.."/"..github_repo_name..".git",
+  branch = (package_version == "scm") and "master" or nil,
+  tag = (package_version ~= "scm") and "v"..package_version or nil,
+}
+
+description = {
+  summary = 'Platform independent system calls for Lua.',
+  detailed = [[
+    Adds a Lua API for making platform independent system calls.
+  ]],
+  license = 'MIT <http://opensource.org/licenses/MIT>',
+  homepage = "https://github.com/"..github_account_name.."/"..github_repo_name,
+}
+
+dependencies = {
+  'lua >= 5.1',
+}
+
+local function make_platform(plat)
+  local defines = {
+    linux = { },
+    unix = { },
+    macosx = { },
+    win32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+    mingw32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+  }
+  local libraries = {
+    linux = { "rt" },
+    unix = { },
+    macosx = { },
+    win32 = { "advapi32", "winmm", "bcrypt" },
+    mingw32 = { },
+  }
+  local libdirs = {
+    linux = nil,
+    unix = nil,
+    macosx = nil,
+    win32 = nil,
+    mingw32 = { },
+  }
+  return {
+    modules = {
+      ['system.core'] = {
+        sources = {
+          'src/core.c',
+          'src/compat.c',
+          'src/time.c',
+          'src/environment.c',
+          'src/random.c',
+          'src/term.c',
+          'src/bitflags.c',
+          'src/wcwidth.c',
+        },
+        defines = defines[plat],
+        libraries = libraries[plat],
+        libdirs = libdirs[plat],
+      },
+    },
+  }
+end
+
+build = {
+  type = 'builtin',
+  platforms = {
+    linux = make_platform('linux'),
+    unix = make_platform('unix'),
+    macosx = make_platform('macosx'),
+    win32 = make_platform('win32'),
+    mingw32 = make_platform('mingw32'),
+  },
+  modules = {
+    ['system.init'] = 'system/init.lua',
+  },
+}
diff --git a/rockspecs/luasystem-0.6.1-1.rockspec b/rockspecs/luasystem-0.6.1-1.rockspec
new file mode 100644
index 0000000..51bbddd
--- /dev/null
+++ b/rockspecs/luasystem-0.6.1-1.rockspec
@@ -0,0 +1,85 @@
+local package_name = "luasystem"
+local package_version = "0.6.1"
+local rockspec_revision = "1"
+local github_account_name = "lunarmodules"
+local github_repo_name = "luasystem"
+
+
+package = package_name
+version = package_version.."-"..rockspec_revision
+
+source = {
+  url = "git+https://github.com/"..github_account_name.."/"..github_repo_name..".git",
+  branch = (package_version == "scm") and "master" or nil,
+  tag = (package_version ~= "scm") and "v"..package_version or nil,
+}
+
+description = {
+  summary = 'Platform independent system calls for Lua.',
+  detailed = [[
+    Adds a Lua API for making platform independent system calls.
+  ]],
+  license = 'MIT <http://opensource.org/licenses/MIT>',
+  homepage = "https://github.com/"..github_account_name.."/"..github_repo_name,
+}
+
+dependencies = {
+  'lua >= 5.1',
+}
+
+local function make_platform(plat)
+  local defines = {
+    linux = { },
+    unix = { },
+    macosx = { },
+    win32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+    mingw32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+  }
+  local libraries = {
+    linux = { "rt" },
+    unix = { },
+    macosx = { },
+    win32 = { "advapi32", "winmm", "bcrypt" },
+    mingw32 = { },
+  }
+  local libdirs = {
+    linux = nil,
+    unix = nil,
+    macosx = nil,
+    win32 = nil,
+    mingw32 = { },
+  }
+  return {
+    modules = {
+      ['system.core'] = {
+        sources = {
+          'src/core.c',
+          'src/compat.c',
+          'src/time.c',
+          'src/environment.c',
+          'src/random.c',
+          'src/term.c',
+          'src/bitflags.c',
+          'src/wcwidth.c',
+        },
+        defines = defines[plat],
+        libraries = libraries[plat],
+        libdirs = libdirs[plat],
+      },
+    },
+  }
+end
+
+build = {
+  type = 'builtin',
+  platforms = {
+    linux = make_platform('linux'),
+    unix = make_platform('unix'),
+    macosx = make_platform('macosx'),
+    win32 = make_platform('win32'),
+    mingw32 = make_platform('mingw32'),
+  },
+  modules = {
+    ['system.init'] = 'system/init.lua',
+  },
+}
diff --git a/rockspecs/luasystem-0.6.2-1.rockspec b/rockspecs/luasystem-0.6.2-1.rockspec
new file mode 100644
index 0000000..7a8549f
--- /dev/null
+++ b/rockspecs/luasystem-0.6.2-1.rockspec
@@ -0,0 +1,85 @@
+local package_name = "luasystem"
+local package_version = "0.6.2"
+local rockspec_revision = "1"
+local github_account_name = "lunarmodules"
+local github_repo_name = "luasystem"
+
+
+package = package_name
+version = package_version.."-"..rockspec_revision
+
+source = {
+  url = "git+https://github.com/"..github_account_name.."/"..github_repo_name..".git",
+  branch = (package_version == "scm") and "master" or nil,
+  tag = (package_version ~= "scm") and "v"..package_version or nil,
+}
+
+description = {
+  summary = 'Platform independent system calls for Lua.',
+  detailed = [[
+    Adds a Lua API for making platform independent system calls.
+  ]],
+  license = 'MIT <http://opensource.org/licenses/MIT>',
+  homepage = "https://github.com/"..github_account_name.."/"..github_repo_name,
+}
+
+dependencies = {
+  'lua >= 5.1',
+}
+
+local function make_platform(plat)
+  local defines = {
+    linux = { },
+    unix = { },
+    macosx = { },
+    win32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+    mingw32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+  }
+  local libraries = {
+    linux = { "rt" },
+    unix = { },
+    macosx = { },
+    win32 = { "advapi32", "winmm", "bcrypt" },
+    mingw32 = { },
+  }
+  local libdirs = {
+    linux = nil,
+    unix = nil,
+    macosx = nil,
+    win32 = nil,
+    mingw32 = { },
+  }
+  return {
+    modules = {
+      ['system.core'] = {
+        sources = {
+          'src/core.c',
+          'src/compat.c',
+          'src/time.c',
+          'src/environment.c',
+          'src/random.c',
+          'src/term.c',
+          'src/bitflags.c',
+          'src/wcwidth.c',
+        },
+        defines = defines[plat],
+        libraries = libraries[plat],
+        libdirs = libdirs[plat],
+      },
+    },
+  }
+end
+
+build = {
+  type = 'builtin',
+  platforms = {
+    linux = make_platform('linux'),
+    unix = make_platform('unix'),
+    macosx = make_platform('macosx'),
+    win32 = make_platform('win32'),
+    mingw32 = make_platform('mingw32'),
+  },
+  modules = {
+    ['system.init'] = 'system/init.lua',
+  },
+}
diff --git a/rockspecs/luasystem-0.6.3-1.rockspec b/rockspecs/luasystem-0.6.3-1.rockspec
new file mode 100644
index 0000000..e70373f
--- /dev/null
+++ b/rockspecs/luasystem-0.6.3-1.rockspec
@@ -0,0 +1,85 @@
+local package_name = "luasystem"
+local package_version = "0.6.3"
+local rockspec_revision = "1"
+local github_account_name = "lunarmodules"
+local github_repo_name = "luasystem"
+
+
+package = package_name
+version = package_version.."-"..rockspec_revision
+
+source = {
+  url = "git+https://github.com/"..github_account_name.."/"..github_repo_name..".git",
+  branch = (package_version == "scm") and "master" or nil,
+  tag = (package_version ~= "scm") and "v"..package_version or nil,
+}
+
+description = {
+  summary = 'Platform independent system calls for Lua.',
+  detailed = [[
+    Adds a Lua API for making platform independent system calls.
+  ]],
+  license = 'MIT <http://opensource.org/licenses/MIT>',
+  homepage = "https://github.com/"..github_account_name.."/"..github_repo_name,
+}
+
+dependencies = {
+  'lua >= 5.1',
+}
+
+local function make_platform(plat)
+  local defines = {
+    linux = { },
+    unix = { },
+    macosx = { },
+    win32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+    mingw32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" },
+  }
+  local libraries = {
+    linux = { "rt" },
+    unix = { },
+    macosx = { },
+    win32 = { "advapi32", "winmm", "bcrypt" },
+    mingw32 = { },
+  }
+  local libdirs = {
+    linux = nil,
+    unix = nil,
+    macosx = nil,
+    win32 = nil,
+    mingw32 = { },
+  }
+  return {
+    modules = {
+      ['system.core'] = {
+        sources = {
+          'src/core.c',
+          'src/compat.c',
+          'src/time.c',
+          'src/environment.c',
+          'src/random.c',
+          'src/term.c',
+          'src/bitflags.c',
+          'src/wcwidth.c',
+        },
+        defines = defines[plat],
+        libraries = libraries[plat],
+        libdirs = libdirs[plat],
+      },
+    },
+  }
+end
+
+build = {
+  type = 'builtin',
+  platforms = {
+    linux = make_platform('linux'),
+    unix = make_platform('unix'),
+    macosx = make_platform('macosx'),
+    win32 = make_platform('win32'),
+    mingw32 = make_platform('mingw32'),
+  },
+  modules = {
+    ['system.init'] = 'system/init.lua',
+  },
+}
diff --git a/spec/04-term_spec.lua b/spec/04-term_spec.lua
index 907f903..5dea046 100644
--- a/spec/04-term_spec.lua
+++ b/spec/04-term_spec.lua
@@ -855,6 +855,32 @@ describe("Terminal:", function()
         assert.is.near(1, timing, 0.5)       -- this also works for MacOS in CI
       end)
 
+
+      it("calls flseep to execute the sleep", function()
+        setbuffer("")
+
+        local sleep_called = false
+        local mysleep = function()
+          sleep_called = true
+        end
+
+        system.readkey(0.01, mysleep)
+        assert.is_true(sleep_called)
+      end)
+
+
+      it("returns errors by fsleep", function()
+        setbuffer("")
+
+        local mysleep = function()
+          return nil, "boom!"
+        end
+
+        local ok, err = system.readkey(1, mysleep)
+        assert.is.falsy(ok)
+        assert.equals("boom!", err)
+      end)
+
     end)
 
 
@@ -876,6 +902,14 @@ describe("Terminal:", function()
       end)
 
 
+      it("reads a control byte for single-byte control characters", function()
+        setbuffer("\000\031\127")
+        assert.are.same({"\000", "ctrl"}, {system.readansi(0)})
+        assert.are.same({"\031", "ctrl"}, {system.readansi(0)})
+        assert.are.same({"\127", "ctrl"}, {system.readansi(0)})
+      end)
+
+
       it("reads a multi-byte characters one at a time", function()
         setbuffer(string.char(226, 130, 172) ..        -- "€"   single
                   string.char(240, 159, 154, 128))     -- "🚀"  double
@@ -902,10 +936,31 @@ describe("Terminal:", function()
       end)
 
 
+      it("reads ANSI escape sequences, just an '<esc>O' (<alt><O> key press)", function()
+        setbuffer("\27O")
+        assert.are.same({"\27O", "ansi"}, {system.readansi(0)})
+      end)
+
+
+      it("reads <alt>+key key presses; <esc>+<key>", function()
+        setbuffer("\27a\27b\27c\27d")
+        assert.are.same({"\27a", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27b", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27c", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27d", "ansi"}, {system.readansi(0)})
+      end)
+
+
+      it("reads <ctrl><alt>[ key press; <esc>+<esc>", function()
+        setbuffer("\27\27\27\27")
+        assert.are.same({"\27\27", "ansi"}, {system.readansi(0)})
+        assert.are.same({"\27\27", "ansi"}, {system.readansi(0)})
+      end)
+
+
       it("returns a single <esc> character if no sequence is found", function()
-        setbuffer("\27\27[A")
-        assert.are.same({"\27", "char"}, {system.readansi(0)})
-        assert.are.same({"\27[A", "ansi"}, {system.readansi(0)})
+        setbuffer("\27")
+        assert.are.same({"\27", "ctrl"}, {system.readansi(0)})
       end)
 
 
@@ -919,6 +974,22 @@ describe("Terminal:", function()
         assert.is.near(1, timing, 0.5)       -- this also works for MacOS in CI
       end)
 
+
+      it("incomplete ANSI sequences will be completed on next call", function()
+        setbuffer("\27[")
+        assert.are.same({nil, "timeout", "\27["}, {system.readansi(0)})
+        setbuffer("A")
+        assert.are.same({"\27[A", "ansi"}, {system.readansi(0)})
+      end)
+
+
+      it("incomplete UTF8 sequences will be completed on next call", function()
+        setbuffer(string.char(240, 159))
+        assert.are.same({nil, "timeout", string.char(240, 159)}, {system.readansi(0)})
+        setbuffer(string.char(154, 128))
+        assert.are.same({"🚀", "char"}, {system.readansi(0)})
+      end)
+
     end)
 
   end)
diff --git a/src/core.c b/src/core.c
index b642074..34e19d8 100644
--- a/src/core.c
+++ b/src/core.c
@@ -4,7 +4,7 @@
 #include <lua.h>
 #include <lauxlib.h>
 
-#define LUASYSTEM_VERSION   "LuaSystem 0.5.1"
+#define LUASYSTEM_VERSION   "LuaSystem 0.6.3"
 
 #ifdef _WIN32
 #define LUAEXPORT __declspec(dllexport)
diff --git a/src/term.c b/src/term.c
index 4cfce95..0325208 100644
--- a/src/term.c
+++ b/src/term.c
@@ -384,6 +384,7 @@ See [setconsolemode documentation](https://learn.microsoft.com/en-us/windows/con
 @treturn[1] boolean `true` on success
 @treturn[2] nil
 @treturn[2] string error message
+@within Terminal_Windows
 @usage
 local system = require('system')
 system.listconsoleflags(io.stdout) -- List all the available flags and their current status
@@ -427,13 +428,12 @@ input flags (for use with `io.stdin`) and `COF` are the output flags (for use wi
 _Note_: See [setconsolemode documentation](https://learn.microsoft.com/en-us/windows/console/setconsolemode)
 for more information on the flags.
 
-
-
 @function getconsoleflags
 @tparam file file file handle to operate on, one of `io.stdin`, `io.stdout`, `io.stderr`
 @treturn[1] bitflags the current console flags.
 @treturn[2] nil
 @treturn[2] string error message
+@within Terminal_Windows
 @usage
 local system = require('system')
 
@@ -497,6 +497,7 @@ The terminal attributes is a table with the following fields:
 @treturn[2] string error message
 @treturn[2] int errnum
 @return error message if failed
+@within Terminal_Posix
 @usage
 local system = require('system')
 
@@ -591,6 +592,7 @@ _Note_: only `iflag`, `oflag`, and `lflag` are supported at the moment. The othe
 @return[2] nil
 @treturn[2] string error message
 @treturn[2] int errnum
+@within Terminal_Posix
 @usage
 local system = require('system')
 
@@ -649,8 +651,105 @@ static int lst_tcsetattr(lua_State *L)
 
 
 
+#ifndef _WIN32
+/*
+reopen FDs for independent file descriptions.
+*/
+static void reopen_fd(lua_State *L, int fd, int flags) {
+    char path[64];
+    int newfd = -1;
+
+    if (fd != STDOUT_FILENO && fd != STDERR_FILENO) {
+        luaL_error(L, "Invalid file descriptor: %d. Only stdout (1) and stderr (2) are supported.", fd);
+    }
+
+    const char *fallback_path = (fd == STDOUT_FILENO) ? "/dev/stdout" :
+                                (fd == STDERR_FILENO) ? "/dev/stderr" : NULL;
+
+    // If fd is a terminal, reopen its actual device (e.g. /dev/ttys003)
+    // Works on all POSIX platforms that have terminals (macOS, Linux, BSD, etc.)
+    if (isatty(fd)) {
+        const char *tty = ttyname(fd);
+        if (tty) {
+            newfd = open(tty, flags);
+        }
+    }
+
+    if (newfd < 0) {
+        // For non-tty: try /dev/fd/N — POSIX-compliant and standard on macOS, Linux, BSD.
+        // This gives a new file description even if the target is a file or pipe.
+        snprintf(path, sizeof(path), "/dev/fd/%d", fd);
+        newfd = open(path, flags);
+    }
+
+    if (newfd < 0) {
+        // Fallback: for platforms/environments where /dev/fd/N doesn't exist.
+        // /dev/stdout and /dev/stderr are standard on Linux, but may not create new descriptions.
+        if (fallback_path) {
+            newfd = open(fallback_path, flags);
+        }
+    }
+
+    if (newfd < 0) {
+        // All attempts failed — raise error with detailed info (call will not return)
+        luaL_error(L, "Failed to reopen fd %d: tried ttyname(), /dev/fd/%d, and fallback %s: %s",
+                    fd, fd, fallback_path ? fallback_path : "(none)", strerror(errno));
+    }
+
+    // Replace the original fd with the new one
+    if (dup2(newfd, fd) < 0) {
+        close(newfd);
+        luaL_error(L, "dup2 failed for fd %d: %s", fd, strerror(errno));
+    }
+
+    close(newfd); // Close the new fd, as dup2 has replaced the original fd with it
+}
+#endif
+
+
+
+/***
+Creates new file descriptions for `stdout` and `stderr`.
+Even if the file descriptors are unique, they still might point to the same
+file description, and hence share settings like `O_NONBLOCK`. This means that
+if one of them is set to non-blocking, the other will be as well. This can
+lead to unexpected behavior.
+
+This function is used to detach `stdout` and `stderr` from the original
+file descriptions, and create new file descriptions for them. This allows
+independent control of flags (e.g., `O_NONBLOCK`) on `stdout` and `stderr`,
+avoiding shared side effects.
+
+Does not modify `stdin` (fd 0), and does nothing on Windows.
+@function detachfds
+@return boolean `true` on success, or throws an error on failure.
+@within Terminal_Posix
+@see setnonblock
+*/
+static int lst_detachfds(lua_State *L) {
+    static int already_detached = 0; // detaching is once per process(not per thread or Lua state)
+    if (already_detached) {
+        lua_pushnil(L);
+        lua_pushliteral(L, "stdout and stderr already detached");
+        return 1;
+    }
+    already_detached = 1;
+
+#ifndef _WIN32
+    // Reopen stdout and stderr with new file descriptions
+    reopen_fd(L, STDOUT_FILENO, O_WRONLY);
+    reopen_fd(L, STDERR_FILENO, O_WRONLY);
+#endif
+
+    lua_pushboolean(L, 1);
+    return 1;
+}
+
+
+
 /***
 Enables or disables non-blocking mode for a file (Posix).
+Check `detachfds` in case there are shared file descriptions.
 @function setnonblock
 @tparam file fd file handle to operate on, one of `io.stdin`, `io.stdout`, `io.stderr`
 @tparam boolean make_non_block a truthy value will enable non-blocking mode, a falsy value will disable it.
@@ -658,9 +757,12 @@ Enables or disables non-blocking mode for a file (Posix).
 @treturn[2] nil
 @treturn[2] string error message
 @treturn[2] int errnum
+@within Terminal_Posix
 @see getnonblock
+@see detachfds
 @usage
 local sys = require('system')
+sys.detachfds() -- detach stdout and stderr, so only stdin becomes non-blocking
 
 -- set io.stdin to non-blocking mode
 local old_setting = sys.getnonblock(io.stdin)
@@ -717,6 +819,8 @@ Gets non-blocking mode status for a file (Posix).
 @treturn[2] nil
 @treturn[2] string error message
 @treturn[2] int errnum
+@within Terminal_Posix
+@see setnonblock
 */
 static int lst_getnonblock(lua_State *L)
 {
@@ -783,6 +887,7 @@ sequences will be buffered internally and returned one byte at a time.
 @treturn[3] nil on error
 @treturn[3] string error message
 @treturn[3] int errnum (on posix)
+@within Terminal_Input
 */
 static int lst_readkey(lua_State *L) {
 #ifdef _WIN32
@@ -803,7 +908,18 @@ static int lst_readkey(lua_State *L) {
     }
 
     wchar_t wc = _getwch();
-    // printf("----\nread wchar_t: %x\n", wc);
+    // printf("----\nread wchar_t: %x\n", (unsigned int)wc);
+
+    if (wc == 0x00 || wc == 0xE0) {
+        // printf("Ignoring scan code: %x\n", (unsigned int)wc);
+        // On Windows, especially with key-repeat, we can get native scancodes even if we've set the console
+        // to ANSI mode. Something, something, terminal not keeping up... These are not valid wide characters,
+        // so we ignore them. Scan codes start with either 0x00 or 0xE0, and have a follow up byte, which we all ignore.
+        // These codes are unique, so we do not risk dropping valid data.
+        _getwch(); // Discard 2nd half of the scan code
+        return 0;
+    }
+
     if (wc == WEOF) {
         lua_pushnil(L);
         lua_pushliteral(L, "read error");
@@ -824,7 +940,7 @@ static int lst_readkey(lua_State *L) {
             }
 
             wchar_t wc2 = _getwch();
-            // printf("read wchar_t 2: %x\n", wc2);
+            // printf("read wchar_t 2: %x\n", (unsigned int)wc2);
             if (wc2 == WEOF) {
                 lua_pushnil(L);
                 lua_pushliteral(L, "read error");
@@ -972,6 +1088,7 @@ Get the width of a utf8 character for terminal display.
 @treturn[1] int the display width in columns of the first character in the string (0 for an empty string)
 @treturn[2] nil
 @treturn[2] string error message
+@within Terminal_UTF-8
 */
 int lst_utf8cwidth(lua_State *L) {
     int width = 0;
@@ -1033,6 +1150,7 @@ Get the width of a utf8 string for terminal display.
 @treturn[1] int the display width of the string in columns (0 for an empty string)
 @treturn[2] nil
 @treturn[2] string error message
+@within Terminal_UTF-8
 */
 int lst_utf8swidth(lua_State *L) {
     const char *utf8_str;
@@ -1083,6 +1201,7 @@ int lst_utf8swidth(lua_State *L) {
 Gets the current console code page (Windows).
 @function getconsolecp
 @treturn[1] int the current code page (always 65001 on Posix systems)
+@within Terminal_UTF-8
 */
 static int lst_getconsolecp(lua_State *L) {
     unsigned int cp = 65001;
@@ -1100,6 +1219,7 @@ Sets the current console code page (Windows).
 @function setconsolecp
 @tparam int cp the code page to set, use `system.CODEPAGE_UTF8` (65001) for UTF-8
 @treturn[1] bool `true` on success (always `true` on Posix systems)
+@within Terminal_UTF-8
 */
 static int lst_setconsolecp(lua_State *L) {
     unsigned int cp = (unsigned int)luaL_checkinteger(L, 1);
@@ -1117,6 +1237,7 @@ static int lst_setconsolecp(lua_State *L) {
 Gets the current console output code page (Windows).
 @function getconsoleoutputcp
 @treturn[1] int the current code page (always 65001 on Posix systems)
+@within Terminal_UTF-8
 */
 static int lst_getconsoleoutputcp(lua_State *L) {
     unsigned int cp = 65001;
@@ -1134,6 +1255,7 @@ Sets the current console output code page (Windows).
 @function setconsoleoutputcp
 @tparam int cp the code page to set, use `system.CODEPAGE_UTF8` (65001) for UTF-8
 @treturn[1] bool `true` on success (always `true` on Posix systems)
+@within Terminal_UTF-8
 */
 static int lst_setconsoleoutputcp(lua_State *L) {
     unsigned int cp = (unsigned int)luaL_checkinteger(L, 1);
@@ -1157,6 +1279,7 @@ static luaL_Reg func[] = {
     { "setconsoleflags", lst_setconsoleflags },
     { "tcgetattr", lst_tcgetattr },
     { "tcsetattr", lst_tcsetattr },
+    { "detachfds", lst_detachfds },
     { "getnonblock", lst_getnonblock },
     { "setnonblock", lst_setnonblock },
     { "_readkey", lst_readkey },
diff --git a/system/init.lua b/system/init.lua
index a81978e..9b71d4d 100644
--- a/system/init.lua
+++ b/system/init.lua
@@ -10,17 +10,21 @@ local system = require 'system.core'
 --- UTF8 codepage.
 -- To be used with `system.setconsoleoutputcp` and `system.setconsolecp`.
 -- @field CODEPAGE_UTF8 The Windows CodePage for UTF8.
+-- @within Terminal_UTF-8
 system.CODEPAGE_UTF8 = 65001
 
 do
-  local backup_mt = {}
+  local backup_indicator = {}
 
   --- Returns a backup of terminal settings for stdin/out/err.
   -- Handles terminal/console flags, Windows codepage, and non-block flags on the streams.
   -- Backs up terminal/console flags only if a stream is a tty.
   -- @return table with backup of terminal settings
+  -- @within Terminal_Backup
   function system.termbackup()
-    local backup = setmetatable({}, backup_mt)
+    local backup = {
+      __type = backup_indicator, -- cannot set a metatable, since autotermrestore uses it for GC
+    }
 
     if system.isatty(io.stdin) then
       backup.console_in = system.getconsoleflags(io.stdin)
@@ -50,8 +54,9 @@ do
   --- Restores terminal settings from a backup
   -- @tparam table backup the backup of terminal settings, see `termbackup`.
   -- @treturn boolean true
+  -- @within Terminal_Backup
   function system.termrestore(backup)
-    if getmetatable(backup) ~= backup_mt then
+    if type(backup) ~= "table" or backup.__type ~= backup_indicator then
       error("arg #1 to termrestore, expected backup table, got " .. type(backup), 2)
     end
 
@@ -106,6 +111,7 @@ do -- autotermrestore
   -- @treturn[1] boolean true
   -- @treturn[2] nil if the backup was already created
   -- @treturn[2] string error message
+  -- @within Terminal_Backup
   function system.autotermrestore()
     if global_backup then
       return nil, "global terminal backup was already set up"
@@ -134,6 +140,7 @@ do
   -- Calls `termbackup` before calling the function and `termrestore` after.
   -- @tparam function f function to wrap
   -- @treturn function wrapped function
+  -- @within Terminal_Backup
   function system.termwrap(f)
     if type(f) ~= "function" then
       error("arg #1 to wrap, expected function, got " .. type(f), 2)
@@ -153,6 +160,7 @@ end
 --- Debug function for console flags (Windows).
 -- Pretty prints the current flags set for the handle.
 -- @param fh file handle (`io.stdin`, `io.stdout`, `io.stderr`)
+-- @within Terminal_Windows
 -- @usage -- Print the flags for stdin/out/err
 -- system.listconsoleflags(io.stdin)
 -- system.listconsoleflags(io.stdout)
@@ -192,6 +200,7 @@ end
 --- Debug function for terminal flags (Posix).
 -- Pretty prints the current flags set for the handle.
 -- @param fh file handle (`io.stdin`, `io.stdout`, `io.stderr`)
+-- @within Terminal_Posix
 -- @usage -- Print the flags for stdin/out/err
 -- system.listconsoleflags(io.stdin)
 -- system.listconsoleflags(io.stdout)
@@ -230,32 +239,40 @@ end
 do
   --- Reads a single byte from the console, with a timeout.
   -- This function uses `fsleep` to wait until either a byte is available or the timeout is reached.
-  -- The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.2 seconds.
+  -- The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.1 seconds.
   -- It returns immediately if a byte is available or if `timeout` is less than or equal to `0`.
   --
   -- Using `system.readansi` is preferred over this function. Since this function can leave stray/invalid
   -- byte-sequences in the input buffer, while `system.readansi` reads full ANSI and UTF8 sequences.
   -- @tparam number timeout the timeout in seconds.
-  -- @tparam[opt=system.sleep] function fsleep the function to call for sleeping.
+  -- @tparam[opt=system.sleep] function fsleep the function to call for sleeping; `ok, err = fsleep(secs)`
   -- @treturn[1] byte the byte value that was read.
   -- @treturn[2] nil if no key was read
-  -- @treturn[2] string error message; `"timeout"` if the timeout was reached.
+  -- @treturn[2] string error message when the timeout was reached (`"timeout"`), or if `sleep` failed.
+  -- @within Terminal_Input
   function system.readkey(timeout, fsleep)
     if type(timeout) ~= "number" then
       error("arg #1 to readkey, expected timeout in seconds, got " .. type(timeout), 2)
     end
 
     local interval = 0.0125
-    local key = system._readkey()
+    local ok
+    local key, err = system._readkey()
     while key == nil and timeout > 0 do
-      (fsleep or system.sleep)(math.min(interval, timeout))
+      if err then
+        return nil, err
+      end
+      ok, err = (fsleep or system.sleep)(math.min(interval, timeout))
+      if not ok then
+        return nil, err
+      end
       timeout = timeout - interval
-      interval = math.min(0.2, interval * 2)
-      key = system._readkey()
+      interval = math.min(0.1, interval * 2)
+      key, err = system._readkey()
     end
 
-    if key then
-      return key
+    if key or err then
+      return key, err
     end
     return nil, "timeout"
   end
@@ -264,7 +281,6 @@ end
 
 
 do
-  local left_over_key
   local sequence -- table to store the sequence in progress
   local utf8_length -- length of utf8 sequence currently being processed
   local unpack = unpack or table.unpack
@@ -278,10 +294,20 @@ do
   -- @tparam number timeout the timeout in seconds.
   -- @tparam[opt=system.sleep] function fsleep the function to call for sleeping.
   -- @treturn[1] string the character that was received (can be multi-byte), or a complete ANSI sequence
-  -- @treturn[1] string the type of input: `"char"` for a single key, `"ansi"` for an ANSI sequence
+  -- @treturn[1] string the type of input: `"ctrl"` for 0-31 and 127 bytes, `"char"` for other UTF-8 characters, `"ansi"` for an ANSI sequence
   -- @treturn[2] nil in case of an error
   -- @treturn[2] string error message; `"timeout"` if the timeout was reached.
   -- @treturn[2] string partial result in case of an error while reading a sequence, the sequence so far.
+  -- The function retains its own internal buffer, so on the next call the incomplete buffer is used to
+  -- complete the sequence.
+  -- @within Terminal_Input
+  -- @usage
+  -- local key, keytype = system.readansi(5)
+  -- if keytype == "char" then ... end -- printable character
+  -- if keytype ~= "char" then ... end -- non-printable character or sequence
+  -- if keytype == "ansi" then ... end -- a multi-byte sequence, but not a UTF8 character
+  -- if keytype ~= "ansi" then ... end -- a valid UTF8 character (which includes control characters)
+  -- if keytype == "ctrl" then ... end -- a single-byte ctrl character (0-31, 127)
   function system.readansi(timeout, fsleep)
     if type(timeout) ~= "number" then
       error("arg #1 to readansi, expected timeout in seconds, got " .. type(timeout), 2)
@@ -292,40 +318,54 @@ do
 
     if not sequence then
       -- no sequence in progress, read a key
-
-      if left_over_key then
-        -- we still have a cached key from the last call
-        key = left_over_key
-        left_over_key = nil
-      else
-        -- read a new key
-        local err
-        key, err = system.readkey(timeout, fsleep)
-        if key == nil then -- timeout or error
-          return nil, err
-        end
+      local err
+      key, err = system.readkey(timeout, fsleep)
+      if key == nil then -- timeout or error
+        return nil, err
       end
 
       if key == 27 then
         -- looks like an ansi escape sequence, immediately read next char
         -- as an heuristic against manually typing escape sequences
         local key2 = system.readkey(0, fsleep)
-        if key2 ~= 91 and key2 ~= 79 then -- we expect either "[" or "O" for an ANSI sequence
-          -- not the expected [ or O character, so we return the key as is
-          -- and store the extra key read for the next call
-          left_over_key = key2
-          return string.char(key), "char"
+        if key2 == nil then
+          -- no key available, return the escape key, on its own
+          sequence = nil
+          return string.char(key), "ctrl"
+
+        elseif key2 == 91 then
+          -- "[" means it is for sure an ANSI sequence
+          sequence = { key, key2 }
+
+        elseif key2 == 79 then
+          -- "O" means it is either an ANSI sequence or just an <alt>+O key stroke
+          -- check if there is yet another byte available
+          local key3 = system.readkey(0, fsleep)
+          if key3 == nil then
+            -- no key available, return the <alt>O key stroke, report as ANSI
+            sequence = nil
+            return string.char(key, key2), "ansi"
+          end
+          -- it's an ANSI sequence, marked with <ESC>O
+          if (key3 >= 65 and key3 <= 90) or (key3 >= 97 and key3 <= 126) then
+            -- end of sequence, return the full sequence
+            return string.char(key, key2, key3), "ansi"
+          end
+          sequence = { key, key2, key3 }
+
+        else
+          -- not an ANSI sequence, but an <alt>+<key2> key stroke, so report as ANSI
+          sequence = nil
+          return string.char(key, key2), "ansi"
         end
 
-        -- escape sequence detected
-        sequence = { key, key2 }
       else
         -- check UTF8 length
         utf8_length = key < 128 and 1 or key < 224 and 2 or key < 240 and 3 or key < 248 and 4
-        if utf8_length  == 1 then
+        if utf8_length == 1 then
           -- single byte character
           utf8_length = nil
-          return string.char(key), "char"
+          return string.char(key), ((key <= 31 or key == 127) and "ctrl" or "char")
         else
           -- UTF8 sequence detected
           sequence = { key }