docs: plan VT100 terminal library integration

docs/INDEX.md

@@ -37,8 +37,9 @@ bisecting *why* a decision was made, not for reading end-to-end).
 - **`future-work-2026-10-25.md`** — TBITSIZE, ADDRESS arithmetic, set
   ordering, complex types, pragmas (TopSpeed vs portable), UTF-8 string
   libraries, collections and the TopSpeed B-tree Toolkit, communications,
-  pyserial, ModBase, network-library design, PIM vs ISO coroutines,
-  external assembly, dynamic-set design and suggested order.
+  pyserial, ModBase, network-library design, terminal escape libraries,
+  PIM vs ISO coroutines, external assembly, dynamic-set design and
+  suggested order.
 
 ## Designs / running records
 

docs/future-work-2026-10-25.md

@@ -4,9 +4,9 @@ This note records the design discussions from 2026-10-25 so the
 questions do not have to be re-derived later.  It covers `TBITSIZE`,
 address arithmetic, set ordering, complex types, pragmas, UTF-8 string
 libraries, collections, the TopSpeed B-tree Toolkit, communications,
-pyserial, ModBase, network-library design, PIM versus ISO coroutines,
-external assembly, and the dynamic-set design.  It is not a commitment
-to implement everything.
+pyserial, ModBase, network-library design, terminal escape libraries,
+PIM versus ISO coroutines, external assembly, and the dynamic-set
+design.  It is not a commitment to implement everything.
 
 **State at the time of writing:** suite 310/310, one-shot fixpoint OK
 (3,845,439 bytes), per-object fixpoint OK (11 objects), corpus
@@ -1637,7 +1637,187 @@ so serial, TCP, loopback and TLS share one protocol-facing interface.
 
 ---
 
-## 13. Suggested order of future work
+## 13. Terminal escape libraries: VT100, VT52, ANSI, ReGIS
+
+The existing `MyWork/VT100` repository contains four useful terminal
+output libraries:
+
+```text
+VT100   strict DEC VT100 escape sequences
+VT52    strict DEC VT52 escape sequences
+Ansi    modern ANSI/xterm superset with colours and modes
+Regis   ReGIS vector graphics commands
+```
+
+There are 27 tests covering the output sequences, plus a `SplitV1`
+helper used by the CPR (cursor-position report) test.
+
+### 13.1 Important distinction: emitter, not emulator
+
+These modules are **escape-sequence emitters**.  They generate output
+such as `ESC[2J`, `ESC[3;7H`, and ReGIS commands.  They do not parse
+incoming terminal data or maintain a screen buffer.
+
+That is the right scope for an output library.  A terminal **emulator**
+— needed to render incoming VT100/ANSI data in the communications
+stack — is a separate parser/screen model and should not be confused
+with these modules.
+
+### 13.2 Porting issues
+
+The modules were written for gm2 `-fiso` and currently depend on:
+
+```text
+STextIO
+NumberIO
+ASCII
+IO
+termios
+FIO
+```
+
+V3 has `STextIO` and `NumberIO`, but the other dependencies are either
+missing or not desirable in a portable library:
+
+- `IO` and `termios` are used only by `Unbuffered`/`Buffered` (raw
+  input for CPR replies);
+- `FIO.StdIn` is used only for the same raw-input support;
+- `ASCII.esc` can be replaced locally;
+- `NumberIO` is PIM-oriented and should not be pulled into a common
+  library just to emit decimal CSI parameters.
+
+The current emitters also write directly to stdout through `STextIO`,
+which prevents using them with a serial or TCP transport.  That is the
+main architectural change needed.
+
+### 13.3 Recommended structure
+
+Add a small output sink:
+
+```modula2
+DEFINITION MODULE TermOut;
+
+TYPE Output = PROCEDURE(s : ARRAY OF CHAR);
+
+PROCEDURE SetOutput(out : Output);
+PROCEDURE WriteString(s : ARRAY OF CHAR);
+PROCEDURE WriteChar(c : CHAR);
+PROCEDURE WriteCard(n : CARDINAL);   (* decimal, no padding *)
+
+END TermOut.
+```
+
+Default output can remain `STextIO`, but it can be redirected to:
+
+- a serial `Transport`;
+- a TCP `Transport`;
+- a file or log;
+- a test buffer;
+- another terminal sink.
+
+Then the terminal modules call `TermOut.WriteString`, `TermOut.WriteChar`
+and `TermOut.WriteCard`, not `STextIO`/`NumberIO` directly.
+
+Move raw-mode input into a separate optional module:
+
+```text
+Tty   — termios save/restore, raw mode, non-blocking reads
+```
+
+`VT100.Unbuffered/Buffered` and the equivalents in `VT52`, `Ansi` and
+`Regis` should be removed from the emitters and replaced by `Tty`
+operations.  This keeps the emitters pure and portable.
+
+### 13.4 Suggested module layout
+
+```text
+lib/common/TermOut.def/.mod    output sink + decimal/ESC helpers
+lib/common/VT100.def/.mod      strict VT100 emitter
+lib/common/VT52.def/.mod       strict VT52 emitter
+lib/common/Ansi.def/.mod       ANSI/xterm emitter
+lib/common/Regis.def/.mod      ReGIS emitter (optional)
+lib/common/Tty.def/.mod        optional POSIX raw-mode input
+```
+
+`lib/common` is the simplest location because it is included by all
+dialects.  A dedicated `lib/term` folder is possible but would require
+build-selection changes.
+
+`Regis` is specialist vector graphics; include it but mark it optional.
+`SplitV1` is test-only and should not become a core library module.
+
+### 13.5 Tests
+
+Convert the existing tests to headless byte tests:
+
+```modula2
+VAR buf : ARRAY [0..1023] OF CHAR;
+
+TermOut.SetOutput(Capture);
+VT100.CursorPosition(3, 7);
+Check(buf, "ESC[3;7H");
+```
+
+Benefits:
+
+- no terminal is required;
+- output is deterministic;
+- the old `od` byte checks become assertions;
+- tests run in the normal V3 suite.
+
+Cover at least:
+
+- VT100 SGR, cursor, erase, tabs, modes, charsets, reports;
+- VT52 cursor, erase, mode, identification;
+- ANSI SGR, colours, cursor, erase, modes, printing;
+- ReGIS enter/exit, lines, circles, text, colours, macros.
+
+The CPR/live-terminal test needs a pty or a real terminal.  Keep it as
+an optional integration test, not part of the default headless suite.
+
+### 13.6 Integration with communications and networking
+
+`TermOut` makes the emitters usable with the communications design:
+
+- serial transport writes through `Transport`;
+- TCP transport writes through `Transport`;
+- `TermOut` points at the transport writer;
+- a future terminal emulator consumes incoming transport bytes and
+  drives a screen model.
+
+This gives a clean split:
+
+```text
+terminal emitters  -> TermOut -> Transport
+terminal emulator  <- Transport <- incoming bytes
+```
+
+### 13.7 Licensing and provenance
+
+The `MyWork/VT100` repository currently has no explicit license file.
+Before vendoring the files into V3:
+
+- confirm it is original/owned code, or
+- keep it as a separate repository/submodule with a clear license, or
+- add a V3-compatible license/provenance header.
+
+The reference documents in `docs/` are independent of the code.
+
+### 13.8 First increment
+
+1. Add `TermOut`.
+2. Port `VT100`, `VT52` and `Ansi` to `TermOut`.
+3. Remove `Unbuffered`/`Buffered` from the emitters.
+4. Add `Tty` separately.
+5. Port `Regis`.
+6. Add headless byte tests.
+7. Keep CPR/live-terminal input tests optional.
+
+No compiler changes are required.
+
+---
+
+## 14. Suggested order of future work
 
 1. `TBITSIZE` (small, standard-facing).
 2. `ADDADR`/`SUBADR`/`DIFADR` (small, ISO SYSTEM).
@@ -1650,14 +1830,16 @@ so serial, TCP, loopback and TLS share one protocol-facing interface.
    and UString modules, then UTF-8 input.
 7. Collections: `Vector`, `Deque`/`Stack`, `HashMap`, then optional
    `BTreeMap`; persistent `BTreeFile` last.
-8. Communications: `Serial`/`Transport` first; protocols and terminal
+8. Terminal emitters: `TermOut`, `VT100`, `VT52`, `Ansi`, optional
+   `Regis`; `Tty` and headless tests.
+9. Communications: `Serial`/`Transport` first; protocols and terminal
    emulation optional.
-9. Network: `Net`/`Transport`, TCP/UDP, `Poll`, then optional TLS/HTTP.
-10. Database: SQLite binding or typed B-tree table layer; dBase III
+10. Network: `Net`/`Transport`, TCP/UDP, `Poll`, then optional TLS/HTTP.
+11. Database: SQLite binding or typed B-tree table layer; dBase III
     only if required.
-11. ISO `COROUTINES` subset, then interrupt/protection layer.
-12. Dynamic `SET CONST` and deep composite copies.
-13. Parser error recovery and diagnostics.
+12. ISO `COROUTINES` subset, then interrupt/protection layer.
+13. Dynamic `SET CONST` and deep composite copies.
+14. Parser error recovery and diagnostics.
 
 External assembly needs no compiler work; document it as the supported
 low-level escape hatch.