ibm5250 0.1.0.dev7__tar.gz → 0.1.0.dev8__tar.gz

{ibm5250-0.1.0.dev7 → ibm5250-0.1.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ibm5250
-Version: 0.1.0.dev7
+Version: 0.1.0.dev8
 Summary: IBM 5250 terminal automation library
 License-File: LICENSE
 Requires-Python: >=3.11

{ibm5250-0.1.0.dev7 → ibm5250-0.1.0.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ibm5250"
-version = "0.1.0.dev7"
+version = "0.1.0.dev8"
 description = "IBM 5250 terminal automation library"
 requires-python = ">=3.11"
 

{ibm5250-0.1.0.dev7 → ibm5250-0.1.0.dev8}/src/ibm5250/__init__.py

@@ -19,6 +19,7 @@ from .constants import (
     FFW,
     SCREEN_COLS,
     SCREEN_ROWS,
+    Attr,
     Command,
     Order,
     TelnetCmd,
@@ -65,6 +66,7 @@ __all__ = [
     "TelnetCmd",
     "TelnetOpt",
     "FFW",
+    "Attr",
     "SCREEN_ROWS",
     "SCREEN_COLS",
     # Address helpers

{ibm5250-0.1.0.dev7 → ibm5250-0.1.0.dev8}/src/ibm5250/connection.py

@@ -26,7 +26,6 @@ from dataclasses import dataclass
 
 from .constants import (
     AID,
-    CC2,
     Command,
     TelnetCmd,
     TelnetOpt,
@@ -49,7 +48,6 @@ _TELNET_OPT_CMD_LEN = 3  # bytes: IAC + command + option (WILL/WONT/DO/DONT)
 # SNA / TN5250E wire-format framing constants
 _GDS_RECORD_ID_HI = 0x12  # SNA GDS record-type identifier, high byte
 _GDS_RECORD_ID_LO = 0xA0  # SNA GDS record-type identifier, low byte
-_SAVE_SCREEN_RESP_CC1 = 0x01  # CC1 value in the Save Screen response variable header
 
 # TN5250E header byte 7 (request/response flags). Real emulators set bit 0x40
 # here to signal the Attention (Attn) key -- a header-only INPUT record with no
@@ -73,6 +71,20 @@ _MAX_NEG_PASSES = 40  # Maximum Telnet option exchange iterations during negotia
 
 _TN5250E_HEADER_LEN = 10
 
+# The header splits into a 6-byte fixed part (length, GDS id, flow type) and a
+# variable-length part whose length is given by byte 6 -- so the 5250 payload
+# begins at ``6 + header[6]`` (normally 6 + 4 = 10).
+_TN5250E_FIXED_HEADER_LEN = 6
+
+
+def _payload_offset(frame: bytes) -> int:
+    """Return the offset of the 5250 payload within a TN5250E *frame*."""
+    offset = _TN5250E_FIXED_HEADER_LEN + frame[_TN5250E_FIXED_HEADER_LEN]
+    if not _TN5250E_HEADER_LEN <= offset <= len(frame):
+        # Malformed variable-header length; fall back to the standard 10 bytes.
+        return _TN5250E_HEADER_LEN
+    return offset
+
 
 @dataclass
 class TN5250EHeader:
@@ -325,23 +337,20 @@ class TN5250Connection:
         frame = _build_tn5250e_frame(req_resp=0x00, opcode=_TN5250E_OP_CANCEL_INVITE)
         self._send_frame(frame, description="Sending Cancel-Invite response")
 
-    def send_save_screen_response(self) -> None:
+    def send_save_screen_response(self, save_id: bytes) -> None:
         """Send the TN5250E-level Save Screen acknowledgment.
 
         When the server issues an ESC+SAVE_SCREEN (0x04 0x02) command the
         terminal must reply with a matching TN5250E frame whose variable header
-        encodes ESC+RESTORE_SCREEN+CC1+CC2 (mirroring what working emulators
-        send).  This is a protocol-level exchange with no 5250 data stream
-        payload.
+        encodes ESC + RESTORE_SCREEN + a two-byte identifier for the screen it
+        just saved.  The host stores that identifier and echoes it back in the
+        Restore Screen command when it wants that particular screen displayed
+        again, so every save must use a distinct *save_id*.
         """
         if not self._tn5250e_active:
             return  # save/restore handshake only occurs in TN5250E mode
 
-        # 4-byte variable header: [ESC, RESTORE_SCREEN, CC1, CC2.RESET_MDT].
-        # byte 9 of the fixed header carries the variable-header length.
-        var_hdr = bytes(
-            [Command.ESC, Command.RESTORE_SCREEN, _SAVE_SCREEN_RESP_CC1, CC2.RESET_MDT]
-        )
+        var_hdr = bytes([Command.ESC, Command.RESTORE_SCREEN]) + bytes(save_id)
         frame = _build_tn5250e_frame(req_resp=0x00, opcode=len(var_hdr), var_hdr=var_hdr)
         self._send_frame(frame, description="Sending Save Screen response")
 
@@ -354,8 +363,8 @@ class TN5250Connection:
                     log.debug("Short TN5250E frame (%d bytes), skipping", len(frame))
                     continue
                 hdr = TN5250EHeader.from_bytes(frame)
-                self._last_recv_opcode = frame[9]  # byte 9: opcode / var_len
-                payload = bytes(frame[_TN5250E_HEADER_LEN:])
+                self._last_recv_opcode = frame[9]  # byte 9: opcode
+                payload = bytes(frame[_payload_offset(frame) :])
                 log.debug(
                     "← TN5250E type=%02X data_type=%02X payload=%d bytes",
                     hdr.record_type,
@@ -365,20 +374,16 @@ class TN5250Connection:
             else:
                 frame_bytes = bytes(frame)
                 # IBM i sends TN5250E-formatted records even when TN5250E was
-                # not formally negotiated.  The 10-byte fixed header begins
-                # with a big-endian 16-bit record length that equals the total
-                # frame size.  Byte 9 of the header is the variable-header
-                # length — that many additional bytes follow before the real
-                # 5250 payload.
+                # not formally negotiated.  The header begins with a big-endian
+                # 16-bit record length that equals the total frame size, and
+                # byte 6 holds the length of the variable header that follows
+                # it — the real 5250 payload starts after that.
                 if len(frame_bytes) >= _TN5250E_HEADER_LEN and int.from_bytes(
                     frame_bytes[:2], "big"
                 ) == len(frame_bytes):
                     hdr = TN5250EHeader.from_bytes(frame_bytes)
                     self._last_recv_opcode = frame_bytes[9]  # byte 9: opcode
-                    var_hdr_len = frame_bytes[
-                        9
-                    ]  # RFC 2877 variable-header length field
-                    skip = _TN5250E_HEADER_LEN + var_hdr_len
+                    skip = _payload_offset(frame_bytes)
                     payload = frame_bytes[skip:]
                     # Server is speaking TN5250E — our responses must include the header too
                     if not self._tn5250e_active:
@@ -387,9 +392,8 @@ class TN5250Connection:
                         )
                         self._tn5250e_active = True
                     log.debug(
-                        "← implicit TN5250E header stripped (fixed=%d var=%d) data_type=%02X payload=%d bytes",
-                        _TN5250E_HEADER_LEN,
-                        var_hdr_len,
+                        "← implicit TN5250E header stripped (%d bytes) data_type=%02X payload=%d bytes",
+                        skip,
                         hdr.data_type,
                         len(payload),
                     )

{ibm5250-0.1.0.dev7 → ibm5250-0.1.0.dev8}/src/ibm5250/constants.py

@@ -83,11 +83,12 @@ class TN5250ESubNeg:
 
 
 class Command:
-    INLINE_WRITE_STRUCTURED_FIELD = (
-        0x02  # Introduces an inline WSF record within a WTD stream
+    ESC = 0x04  # precedes every 5250 command in a record
+    CLEAR_UNIT = 0x40  # erase the display, reset it to the primary size (24×80)
+    CLEAR_UNIT_ALTERNATE = (
+        0x20  # erase the display, switch to the alternate size (27×132);
+        # followed by a one-byte parameter (0x00 or 0x80)
     )
-    ESC = 0x04  # precedes Write Structured Field inline
-    CLEAR_UNIT = 0x40  # erase the display and format table
     WRITE_TO_DISPLAY = (
         0x11  # main screen update command; followed by CC1/CC2 and orders
     )
@@ -105,16 +106,16 @@ class Command:
 
 # Write to Display control characters (CC1 / CC2)
 class CC1:
-    """Control Character 1 — first byte after WTD command.
+    """Control Character 1 — first byte after the WTD command.
 
-    Only bits 0-2 are defined by the IBM 5250 spec; bits 3-7 are reserved.
-    Keyboard lock/unlock is controlled exclusively by CC2, not CC1.
+    CC1 selects which Modified Data Tags and input-field buffers the host wants
+    reset before the write is applied.  It does **not** erase the screen and it
+    does **not** change the screen dimensions — those are driven exclusively by
+    the Clear Unit (:data:`Command.CLEAR_UNIT`) and Clear Unit Alternate
+    (:data:`Command.CLEAR_UNIT_ALTERNATE`) commands.
     """
 
     RESET = 0x00
-    CLEAR_UNIT = 0x20  # Erase entire screen before write
-    CLEAR_UNIT_ALT = 0x40  # Erase screen using alternate screen dimensions
-    CLEAR_FORMAT_TABLE = 0x60  # Discard field definitions only; no screen erase
     SOUND_ALARM = 0x80  # Audible alarm
 
 
@@ -133,22 +134,32 @@ class CC2:
 # ---------------------------------------------------------------------------
 
 class Order:
+    """5250 orders embedded in a Write to Display data stream.
+
+    Note these are *5250* order codes -- they differ from the 3270 codes of the
+    same name (e.g. 5250 Repeat to Address is 0x02, not 0x3C).
+    """
+
     START_OF_HEADER = 0x01  # Start of Header (variable-length; skip past it)
+    REPEAT_TO_ADDRESS = 0x02  # Repeat to Address  — 2 address bytes + 1 fill char
+    ERASE_TO_ADDRESS = (
+        0x03  # Erase to Address   — 2 address bytes + length + attribute types
+    )
     TRANSPARENT_DATA = 0x10  # Transparent Data   — 2-byte length + raw EBCDIC
     SET_BUFFER_ADDRESS = 0x11  # Set Buffer Address — 2 address bytes
-    ERASE_TO_ADDRESS = (
-        0x12  # Erase to Address        — 2 address bytes (fill with nulls)
+    WRITE_EXTENDED_ATTRIBUTE = (
+        0x12  # Write Extended Attribute — 2 bytes; not emulated
     )
     INSERT_CURSOR = 0x13  # Insert Cursor            — 2 address bytes; marks cursor pos
     MOVE_CURSOR = 0x14  # Move Cursor              — 2 address bytes
-    GROUP_ERASE_TO_ADDRESS = 0x16  # Group Erase to Address   — 2 address bytes (fill with nulls, within field group)
+    WRITE_DISPLAY_STRUCTURED_FIELD = (
+        0x15  # Write to Display Structured Field — 2-byte length + payload
+    )
     START_FIELD = 0x1D  # Start Field        — 2-byte FFW [+ 2-byte FCW pairs]
-    SET_ATTRIBUTE = 0x28  # Set Attribute      — 1 attribute type + 1 value byte
-    MODIFY_FIELD = 0x2C  # Modify Field       — like SF but doesn't clear data
-    REPEAT_TO_ADDRESS = 0x3C  # Repeat to Address  — 2 address bytes + 1 fill char
 
-_KNOWN_ORDERS = frozenset(
-    v for k, v in vars(Order).items() if not k.startswith("_")
+
+KNOWN_ORDERS = frozenset(
+    v for k, v in vars(Order).items() if isinstance(v, int) and not k.startswith("_")
 )
 
 # ---------------------------------------------------------------------------
@@ -218,36 +229,56 @@ class AID:
 
 
 class FFW:
-    """Field Format Word bits (byte 0 and byte 1 of the 2-byte FFW)."""
+    """Field Format Word bits (byte 0 and byte 1 of the 2-byte FFW).
 
-    # Byte 0
+    Note the FFW carries *behaviour* only.  A field's visual appearance comes
+    from the separate attribute byte that follows the FFW/FCWs in the SF order
+    (see :class:`Attr`).
+    """
+
+    # Byte 0 — bit 0x40 is the "this is an FFW" identifier and is always set.
+    IDENTIFIER = 0x40  # Marks the byte as a Field Format Word rather than an attribute
     BYPASS = 0x20  # Protected field — no input allowed (read-only)
     DUP_ENABLE = 0x10  # Dup key enabled — user can duplicate the previous field's value
-    MDT = 0x01  # Modified Data Tag — set when the field has been touched
-    AUTO_ENTER = 0x08  # Auto Enter — automatically submit when the field is filled
-    FER = 0x04  # Field Exit Required — user must press Field Exit before leaving
-
-    # Byte 1 (keyboard shift / display attribute)
+    MDT = 0x08  # Modified Data Tag — set when the field has been touched
+    # Byte 0, low 3 bits — field type (keyboard shift)
     ALPHA_SHIFT = 0x00  # Alphabetic shift — accepts any character
-    ALPHA_ONLY = 0x04  # Alphabetic only — rejects digits and special characters
-    NUM_SHIFT = 0x08  # Numeric shift — defaults keyboard to numeric mode
-    NUM_ONLY = 0x18  # Numeric only — rejects non-numeric input
-    KATA_SHIFT = 0x0C  # Katakana shift — Japanese katakana character entry
-    DIGITS_ONLY = 0x1C  # Digits only — accepts 0–9 with no sign
-    IO_ONLY = 0x10  # Inhibit Output only — field is write-protected from the keyboard
-    SIGNED_NUM = 0x14  # Signed numeric — accepts digits plus a trailing sign character
-    # Display attribute (high nibble of byte 1)
-    DISP_NORM = 0x00  # Normal — green on black
-    DISP_HIGH = 0x20  # High intensity — bright green on black
-    DISP_RI = 0x40  # Reverse image — black on green
-    DISP_RI_HIGH = 0x60  # Reverse image high intensity — bright black on green
-    DISP_UNDER = 0x80  # Underline — green with underline
-    DISP_UNDER_HI = 0xA0  # Underline high intensity — bright green with underline
-    DISP_BLINK = 0xC0  # Blink — flashing field
-    NON_DISPLAY = 0xE0  # Non-display — invisible; used for password entry
-    DISPLAY_ATTR_MASK = (
-        0xE0  # Bitmask for the display attribute field (high 3 bits of byte 1)
-    )
+    ALPHA_ONLY = 0x01  # Alphabetic only — rejects digits and special characters
+    NUM_SHIFT = 0x02  # Numeric shift — defaults keyboard to numeric mode
+    NUM_ONLY = 0x03  # Numeric only — rejects non-numeric input
+    KATA_SHIFT = 0x04  # Katakana shift — Japanese katakana character entry
+    DIGITS_ONLY = 0x05  # Digits only — accepts 0–9 with no sign
+    MAG_READER = 0x06  # Magnetic stripe reader input only
+    SIGNED_NUM = 0x07  # Signed numeric — accepts digits plus a trailing sign character
+    FIELD_TYPE_MASK = 0x07  # Bitmask for the field type bits of byte 0
+
+    # Byte 1
+    AUTO_ENTER = 0x80  # Auto Enter — automatically submit when the field is filled
+    FER = 0x40  # Field Exit Required — user must press Field Exit before leaving
+    MONOCASE = 0x20  # Monocase — lower-case input is folded to upper case
+    MANDATORY = 0x08  # Mandatory entry — the field may not be left empty
+    RIGHT_ZERO = 0x05  # Right-adjust, zero fill
+    RIGHT_BLANK = 0x06  # Right-adjust, blank fill
+    MANDATORY_FILL = 0x07  # Mandatory fill — the field must be filled completely
+    MANDATORY_FILL_MASK = 0x07  # Bitmask for the adjust/fill bits of byte 1
+
+
+class Attr:
+    """5250 display attribute byte values (0x20-0x3F).
+
+    Every attribute occupies one display position and governs the appearance of
+    the characters that follow it until the next attribute byte.
+    """
+
+    NORMAL = 0x20  # Green
+    REVERSE = 0x21  # Green, reverse image
+    HIGH_INTENSITY = 0x22  # White
+    UNDERLINE = 0x24  # Green, underlined
+    NON_DISPLAY = 0x27  # Invisible — used for passwords and command strings
+    RED = 0x28  # Red
+    BASE = 0x20  # All attribute bytes have this bit pattern in their high bits
+    MASK = 0xE0  # ``byte & MASK == BASE`` identifies an attribute byte
+    NON_DISPLAY_MASK = 0x07  # ``byte & MASK == 0x07`` means non-display
 
 
 # ---------------------------------------------------------------------------
@@ -436,6 +467,10 @@ SCREEN_COLS = 80
 SCREEN_ROWS_27 = 27  # 27×132 model
 SCREEN_COLS_132 = 132
 
+# Length of the screen identifier the workstation returns in its Save Screen
+# acknowledgment and that the host echoes back in a Restore Screen command.
+SAVE_SCREEN_ID_LEN = 2
+
 EBCDIC_SPACE = 0x40
 EBCDIC_NULL = 0x00
 

{ibm5250-0.1.0.dev7 → ibm5250-0.1.0.dev8}/src/ibm5250/data-stream-logic.md

@@ -19,7 +19,11 @@ The **TN5250Connection** manages the TCP socket to the IBM i (AS/400) host.
 1. Reads bytes from the socket into a buffer.
 2. Scans for the IAC-EOR (Interpret As Command — End Of Record) sequence (0xFF 0xEF) which marks the end of a logical record.
 3. Un-escapes any doubled IAC bytes (0xFF 0xFF → 0xFF).
-4. If TN5250E is active, strips the 10-byte header + variable header → returns the raw 5250 payload.
+4. If TN5250E is active, strips the header → returns the raw 5250 payload. The
+   header is six fixed bytes followed by a variable part whose **length is byte 6**
+   (normally 4, giving the familiar 10-byte total), so the payload starts at
+   `6 + frame[6]`. Byte 9 is the _opcode_, not the header length — confusing the
+   two silently truncates the first bytes of the payload.
 5. If the socket has no data within the timeout, raises **RecvTimeout**.
 
 ### Sending (`send_record`)
@@ -33,7 +37,12 @@ The **TN5250Connection** manages the TCP socket to the IBM i (AS/400) host.
 
 ### Save Screen Response (`send_save_screen_response`)
 
-When the server issues a SAVE_SCREEN command, the terminal must reply with a special TN5250E-framed acknowledgment (no 5250 payload — just a variable header encoding ESC + RESTORE_SCREEN + CC1 + CC2). This tells the server "I've saved the screen; you can now overlay it."
+When the server issues a SAVE_SCREEN command, the terminal must reply with a
+TN5250E-framed acknowledgment carrying `ESC + RESTORE_SCREEN + a two-byte
+identifier`. This tells the server "I've saved the screen under this name; you
+can now overlay it." **Every save must use a distinct identifier** — the server
+stores it and echoes it back later to say _which_ saved screen it wants
+restored. See [Save/Restore Screen Flow](#saverestore-screen-flow).
 
 ---
 
@@ -43,28 +52,37 @@ The **DataStreamParser** takes a raw 5250 payload (one record from the connectio
 
 ### Record Structure
 
-Every 5250 record starts with a **command byte**:
-
-| Command                         | Meaning                                                                             |
-| ------------------------------- | ----------------------------------------------------------------------------------- |
-| `0x11` (Write to Display)       | Main screen update — followed by CC1, CC2, then orders/data                         |
-| `0x40` (Clear Unit)             | Clears the display and field definitions                                            |
-| `0x02` (Save Screen)            | Server wants to save the current screen (same format as WTD)                        |
-| `0x12` (Restore Screen)         | Server wants to restore a previously saved screen                                   |
-| `0x04` (ESC)                    | Escape prefix — next byte is the real command (Clear Unit, WTD, WSF, Save, Restore) |
-| `0xF3` (Write Structured Field) | Carries structured data like Query commands                                         |
-| `0x42/0x52/0x72/0x62`           | Read commands — server asks client to send back screen/field data                   |
-| `0x21` (Write Error Code)       | Display error on status line                                                        |
-| `0x50` (Clear Format Table)     | Discard field definitions                                                           |
+Every command in a record is introduced by **ESC (`0x04`)**, and one record may
+carry several commands back to back:
+
+| Command                         | Meaning                                                                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `0x11` (Write to Display)       | Main screen update — followed by CC1, CC2, then orders/data                              |
+| `0x40` (Clear Unit)             | Erases the display and field definitions and selects the **primary** size (24×80)        |
+| `0x20` (Clear Unit Alternate)   | Erases the display and selects the **alternate** size (27×132); takes one parameter byte |
+| `0x02` (Save Screen)            | Server wants the client to save the current screen                                       |
+| `0x12` (Restore Screen)         | Server wants a previously saved screen restored; followed by its two-byte identifier     |
+| `0xF3` (Write Structured Field) | Carries structured data like Query commands                                              |
+| `0x42/0x52/0x72/0x62`           | Read commands — server asks client to send back screen/field data                        |
+| `0x21` (Write Error Code)       | Display error on status line                                                             |
+| `0x50` (Clear Format Table)     | Discard field definitions                                                                |
+
+### Screen size
+
+The display size is **absolute and set only by the clear commands**: Clear Unit
+selects 24×80, Clear Unit Alternate selects 27×132. It is never a toggle, and it
+is never inferred from out-of-range buffer addresses. Getting this wrong is what
+made a screen returning from a 132-column layout keep rendering as 27×132 with
+stale content bleeding through.
 
 ### Control Characters (CC1 / CC2)
 
-After a WTD or Save Screen command, two bytes control screen-level behavior:
+Write to Display is followed by two control bytes:
 
-- **CC1** — Screen clear mode:
-  - `0x20`: Clear the entire screen before writing new data
-  - `0x40`: Clear and switch to alternate screen size (24×80 ↔ 27×132)
-  - `0x00`: Don't clear — overlay on existing content
+- **CC1** — Lock/reset flags. Notably CC1 **neither erases the screen nor
+  changes its dimensions**; only the clear commands above do that.
+  - `0x01`/`0x02`: Reset pending AIDs / unlock after the write
+  - `0x04`: Sound the alarm
 
 - **CC2** — Keyboard and field flags:
   - `0x08`: Unlock the keyboard (let the user type)
@@ -75,24 +93,49 @@ After a WTD or Save Screen command, two bytes control screen-level behavior:
 
 After the command + CC bytes, the rest of the record is a stream of **orders** intermixed with **data bytes**:
 
-| Order                                                  | What it does                                                                                                                                                                                                                                                        |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **SBA** — Set Buffer Address (`0x11`) + row + col      | Move the write position to a specific screen cell                                                                                                                                                                                                                   |
-| **SF** — Start Field (`0x1D`) + FFW [+ FCWs]           | Define a new input/output field at the current position. The FFW (Field Format Word, 2 bytes) defines field type — bypass/input, numeric, non-display, etc. Optional FCW (Field Control Word) pairs add behaviours like mandatory entry, right-adjust, or monocase. |
-| **MF** — Modify Field (`0x2C`) + FFW [+ FCWs]          | Modify an existing field's attributes                                                                                                                                                                                                                               |
-| **IC** — Insert Cursor (`0x13`)                        | Place the cursor at the 2-byte address that follows (falls back to the current position only when no address bytes remain)                                                                                                                                          |
-| **MC** — Move Cursor (`0x14`) + row + col              | Move the cursor to a specific position                                                                                                                                                                                                                              |
-| **RA** — Repeat to Address (`0x3C`) + row + col + char | Repeat a character from current position up to the target                                                                                                                                                                                                           |
-| **EA** — Erase to Address (`0x12`) + row + col         | Erase (fill with nulls) from current position to target                                                                                                                                                                                                             |
-| **TD** — Transparent Data (`0x10`) + length + data     | Write raw bytes (transparent, no order interpretation)                                                                                                                                                                                                              |
-| **SA** — Set Attribute (`0x28`) + type + value         | Set a display attribute (colour, underline, etc.)                                                                                                                                                                                                                   |
-| **SOH** — Start of Header (`0x01`) + length + data     | Metadata block, skipped                                                                                                                                                                                                                                             |
+These are the **5250** order codes; several share a name with a 3270 order but
+use a different byte value (5250 Repeat to Address is `0x02`, not `0x3C`).
+
+| Order                                                        | What it does                                                                                                                                 |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **SOH** — Start of Header (`0x01`) + length + data           | Metadata block, skipped                                                                                                                      |
+| **RA** — Repeat to Address (`0x02`) + row + col + char       | Repeat a character from the current position up to **and including** the target                                                              |
+| **EA** — Erase to Address (`0x03`) + row + col + len + types | Erase (fill with nulls) from the current position through the target. `len` counts itself plus the extended-attribute type bytes that follow |
+| **TD** — Transparent Data (`0x10`) + length + data           | Write raw bytes (transparent, no order interpretation)                                                                                       |
+| **SBA** — Set Buffer Address (`0x11`) + row + col            | Move the write position to a specific screen cell                                                                                            |
+| **WEA** — Write Extended Attribute (`0x12`) + type + value   | Extended character buffer attribute; not emulated, operands are consumed                                                                     |
+| **IC** — Insert Cursor (`0x13`)                              | Place the cursor at the 2-byte address that follows (falls back to the current position only when no address bytes remain)                   |
+| **MC** — Move Cursor (`0x14`) + row + col                    | Move the cursor to a specific position                                                                                                       |
+| **WDSF** — Write to Display Structured Field (`0x15`)        | GUI constructs (windows, scrollbars); not emulated, the payload is skipped                                                                   |
+| **SF** — Start Field (`0x1D`)                                | Define a field at the current position — see below                                                                                           |
 
 Anything that isn't a recognized order byte is treated as **EBCDIC (Extended Binary Coded Decimal Interchange Code)** character data and written sequentially into the screen buffer.
 
-### Inline Structured Fields (0x02 / 0x04 in the order stream)
+### Attribute bytes
+
+Bytes in the range **`0x20`–`0x3F`** are display attributes. They are _data_:
+each one occupies a screen position (rendered as a blank) and governs the
+appearance of everything after it until the next attribute. `0x27` — more
+precisely any attribute whose low three bits are all set — means _non-display_,
+which is how password fields and hidden command strings are rendered blank.
+
+Because attributes are the only bytes with that bit pattern, they double as the
+terminator for the variable-length part of an SF order.
+
+### Start Field (SF)
 
-IBM i sometimes embeds 3–4 byte attribute markers (`0x02 XX YY` or `0x04 XX YY ZZ`) inline within the data stream to carry extended colour/highlight info. The parser identifies these and skips over them without writing them as screen text.
+    SF (0x1D) [FFW1 FFW2 [FCW1 FCW2]...] ATTR LEN_HI LEN_LO
+
+- An **output-only** field omits the FFW and FCWs entirely: the byte straight
+  after SF is then the attribute.
+- The **FFW** (Field Format Word) defines field behaviour — bypass/input,
+  keyboard shift, mandatory entry, and so on. Byte 0 always has bit `0x40` set,
+  which is how it is told apart from an attribute byte.
+- Zero or more **FCW** (Field Control Word) pairs may follow; the chain ends at
+  the first attribute byte, _not_ at a continuation bit.
+- The attribute byte is written at the field's start position, and the field's
+  length is the **two bytes after it** — it is not derived from an FCW and it is
+  not inferred from where the next field begins.
 
 ### Write Structured Field (WSF / Query)
 
@@ -167,8 +210,9 @@ This is the central method — it:
 2. Feeds it through `parser.parse()` to get a list of `DSEvent` objects.
 3. Iterates through events looking for special commands:
    - **QUERY** → sends back a Query Reply with terminal capabilities
-   - **SAVE_SCREEN** → deep-copies the current `Screen` onto a stack, sends the save-screen acknowledgment to the server
-   - **RESTORE_SCREEN** → pops the saved screen off the stack, replaces the current screen with it, then applies any remaining events from the same record on top
+   - **SAVE_SCREEN** → deep-copies the current `Screen`, files it under a fresh identifier, and returns that identifier in the save-screen acknowledgment
+   - **RESTORE_SCREEN** → looks the identifier the server sent up among the saved screens, makes it current (dropping any newer saves), resizes the parser to its dimensions, then applies any remaining events from the same record on top
+   - **RESIZE_SCREEN** → re-creates the parser and screen at the new dimensions
 4. If no RESTORE occurred, applies all events to the screen normally.
 5. **Post-RESTORE keyboard drain**: After restoring a screen, the keyboard is locked (because it was locked when saved). The server sends a follow-up record to unlock it. The terminal tries one more `_recv_and_apply()` to consume that unlock record. If nothing comes (RecvTimeout), it moves on.
 
@@ -194,12 +238,30 @@ This is the central method — it:
 This is how the server does "popup" screens (like overlaying a detail view on a list):
 
 1. Server sends **SAVE_SCREEN** → terminal saves a copy of the current screen
+   under a fresh two-byte identifier and returns that identifier in the Save
+   Screen response
 2. Server sends a normal WTD with new content → terminal shows the popup
 3. User interacts with the popup (sends keys, gets responses)
-4. Server sends **RESTORE_SCREEN** → terminal swaps back to the saved screen
+4. Server sends **RESTORE_SCREEN + identifier** → terminal swaps back to _that_
+   saved screen and discards any screens saved after it
 5. Server sends a follow-up WTD to unlock the keyboard on the restored screen
 
-The tricky part: after step 4, the restored screen has `keyboard_locked = True` (it was saved right after the client sent an AID key). The terminal must consume the unlock record (step 5) before attempting the next `send_key`, otherwise the server rejects the input.
+Saves nest, so this is **not** a stack the terminal may simply pop: the server
+decides how far to unwind and names the screen it wants. Unwinding two levels
+in one go — restore `04 05`, Clear Unit, restore `03 04` — is normal, and
+popping blindly restores the wrong screen.
+
+A restored screen brings its own dimensions with it, so the parser must be
+re-created to match whenever one is restored.
+
+The other tricky part: after step 4, the restored screen has
+`keyboard_locked = True` (it was saved right after the client sent an AID key).
+The terminal must consume the unlock record (step 5) before attempting the next
+`send_key`, otherwise the server rejects the input.
+
+Screens restored this way are usually followed by _partial_ updates that repaint
+only the parts of the screen that changed, so the restored snapshot has to be
+byte-accurate — any error in it survives into the final display.
 
 ---