SOURCE VIEWER

CH12_ENTITY_B_r007.s

Original bytes preserved. This is a browser-readable view.

DOWNLOAD ORIGINAL ↓

; ======================================================================
; CS617 Chapter 12 - Recursion Angel - Entity B r007
; PB-2000C standalone language-card ROM
; Alex Barragan & ChatGPT (Sol)
;
; AUTHORITY
;   Functional baseline derived from contract/NOTES.angel.lisp plus the Chapter 12
;   SOLVER_INPUT_MANIFEST allowlisted common HD61700 / PB-2000C context.
;   r005 conforms to the user-authorized post-test Angelical augmentation
;   work/nfr_authority/NFRs.angel.lisp (NF-01..NF-07, rev 2).
;   No peer recursion source, algorithms, listings, screenshots, teaching
;   material, or implementation history are used.
;
; IMPLEMENTATION BOUNDARY
;   New Entity B HOW.  The language-card scaffold, BOOT-derived direct
;   keyboard scanner/table, and firmware text-output mechanism are inherited
;   from allowlisted pre-recursion CS617 precedent and are marked below.
;
; VALIDATION BOUNDARY
;   r002 is the authoritative-assembler-clean pre-NFR baseline.
;   r006 assembled and ran but the typed-N cursor still did not visibly blink.
;   Piotr Piatek then supplied the missing machine-level fact: cursor blinking is
;   serviced from inside C-ROM CRTKY (&H0460), which periodically calls &H0364
;   while waiting for a key.  A pre-scan loop prevents CRTKY from owning idle time.
;   Piotr's recommended solution is to remove that pre-scan and use the proper
;   language-card BRK handler at &H0DAA.  The narrowly inspected accepted benchmark
;   independently confirms that &H0DAA is the language BRK vector.  r007 therefore
;   removes the N-editor raw gate, restores &H0DAA to BRK exit, and lets CRTKY own
;   the blocking wait.  No manual &H0364 call or 08D8->08D7 workaround is used.
;   This r007 source has not yet been assembled by HD61 ASSEMBLER Rev. 0.45
;   and has not been run in emulator or physical hardware.  build/ remains
;   external/toolchain-owned; source/static checks are not target evidence.
;
; CONTRACT SHAPE
;   - one ROM, cold splash -> top menu automatically
;   - independent retained Queens N and Hanoi N, each 1..10
;   - one shared private 32x24 character VT surface
;   - public VT_CLEAR, VT_WRITE, VT_VIEW only
;   - recursive all-solution N-Queens
;   - recursive minimal three-peg Hanoi with paged replayable move stream
; ======================================================================

        ORG     0
        LEVEL   0

; --------------------------- firmware / keys ---------------------------
OFFCHK: EQU     &H04EF
WORK1:  EQU     &H0CE6
SETBK:  EQU     &H0276
CRTKY:  EQU     &H0460
KEYMD:  EQU     &H09E4
SYSCLR: EQU     &H3169
SETLCD: EQU     &H328F
SET4LN: EQU     &H28D8
EDCSR:  EQU     &H08CB
CSREN:  EQU     &H22E0
CSRDIS: EQU     &H22FA
SSPTP:  EQU     &H0FEF
USPTP:  EQU     &H0CE2
SSPBT:  EQU     &H0EEE
RCS:    EQU     SSPBT+16
KEYMENU:EQU     &H9C
KEYBRK: EQU     &H9D
KEYF1:  EQU     &HFC
KEYF2:  EQU     &HFD
KEYF3:  EQU     &HFE
KEYF4:  EQU     &HFF
KEYEXE: EQU     &H0D
KEYBS:  EQU     &H08
KEYUP:  EQU     &H1E
KEYDN:  EQU     &H1F
KEYQ:   EQU     &H51

; ------------------------------- RAM map -------------------------------
; UA=&H14: IX/IY -> bank-1 RAM, IZ -> bank-0 ROM, PC -> bank-0 ROM.
VT_BASE:EQU     &H2000      ; 768 bytes: 24 x 32
VT_SIZE:EQU     &H0300
STRBUF: EQU     &H2300      ; 64-byte transient string scratch

WS_QN:  EQU     &H2340      ; retained Queens N
WS_HN:  EQU     &H2341      ; retained Hanoi N
Q_COLS: EQU     &H2342      ; 10 bytes, row -> selected column
WS_STOP:EQU     &H234C      ; 0 continue, 1 MENU/top
WS_QSPIN:EQU    &H234D      ; 0..3
WS_QTICK:EQU    &H234E      ; byte work quantum counter
WS_QCNT:EQU     &H2350      ; word solutions found
WS_VTOP:EQU     &H2352      ; VT_VIEW top line 1..21
WS_DPTR:EQU     &H2354      ; word display RAM pointer
WS_DIDX:EQU     &H2356      ; byte display loop index
WS_NEWT:EQU     &H2357      ; new-N typed value
WS_NDIG:EQU     &H2358      ; new-N digit count
WS_HMOVE:EQU    &H235A      ; word moves generated
WS_HFIRST:EQU   &H235C      ; word first move on current page
WS_HLAST:EQU    &H235E      ; word last move on current page
WS_HPGCNT:EQU   &H2360      ; byte moves on current page 0..88
WS_HLINE:EQU    &H2361      ; next VT line 2..23
WS_HSLOT:EQU    &H2362      ; next field 0..3

; -------------------------- language-card header -----------------------
; Canonical pre-recursion standalone scaffold.  12 10 is provisional.
        DB      &H43,&H4D
        DB      &HFF,&HFF,&HFF,&HFF
        DB      &H01,&H04,&H12,&H10
        DB      &HFF,&HFF,&HFF,&HFF
        DB      &HFF,&HFF,&HFF,&HFF
        DB      &HFF,&HFF,&HFF,&HFF
        DB      &HFF,&HFF,&HFF,&HFF
        DB      &HFF
        DB      &H03
        DB      &HC0
        DB      &HFF,&HFF,&HFF

; ======================================================================
; INHERITED PRE-RECURSION C-ROM BANK-CALL BRIDGE
; Byte-for-byte instruction pattern follows allowlisted accepted Chapter 06
; precedent.  r003/r004 used it for cursor enable/disable but omitted the validated C-ROM
; runtime initialization context.  r005 restores that context
; required by NF-02.  It is support code, not new recursion application HOW.
; ======================================================================
        ORG     &H0C20

RCS_TOP:
        GST     UA,$6
        PHS     $6
        LDW     $6,SETBK-1
        PHSW    $7
        PST     UA,&H54
        JP      $28

_SYSCAL:
        PST     UA,&H45
        LDW     $6,&H0C10
        ST      $31,($6)
        CAL     RCS
        PST     UA,&H45
        LDW     $6,&H0C10
        LD      $28,3
        ST      $28,($6)
        PST     UA,&H54
        RTN
RCS_END:

        ORG     &H0C50

SYSCAL:
        PST     UA,&H55
        JP      RCS+(_SYSCAL-RCS_TOP)

; ======================================================================
; INHERITED BOOT-DERIVED DIRECT KEYBOARD SCANNER
; Based on allowlisted Chapter 01 accepted lineage.  Entity B changes only
; the BRK disposition: physical BRK is returned as KEYBRK so VT_VIEW can
; report stop reason 02 before the consumer takes the normal BRK exit.
; ======================================================================
        ORG     &H0C60

INKEY:
        CAL     OFFCHK
        LD      $17,$31
        LD      $0,&H4B

IKEYLP:
        PST     IA,$0
        GRE     KY,$1
        GRE     KY,$1
        DID     $2
        ANCW    $1,$1
        JR      Z,IKEY40

        SBC     $0,&H41
        JP      Z,IKEYBRK

IKEY10:
        LD      $3,$31
IKEY20:
        BIDW    $2
        JR      C,IKEY30
        AD      $3,$30,IKEY20
IKEY30:
        LD      $5,$0
        SB      $5,$30
        BIU     $5
        BIU     $5
        LD      $4,$5
        BIU     $4
        BIU     $4
        SB      $4,$5

        PST     UA,&H44
        PRE     IX,KEYSCAN
        LDD     $0,(IX+$4)
        LDD     $0,(IX+$3)
        PST     UA,&H54
        JR      IKEY50

IKEYBRK:
        LD      $0,KEYBRK
        LD      $17,$30
        JP      IKEYRET

IKEY40:
        SB      $0,$30
        JR      LNZ,IKEYLP
        LD      $0,$31
IKEY50:
        AN      $0,$0
        JR      Z,IKEYRET
        LD      $17,$30
IKEYRET:
        LDW     $15,WORK1
        ST      $0,($15)
        RTN

; ------------------------- canonical vectors ---------------------------
        ORG     &H0D80
        JP      MAIN
        JP      TRAP
        JP      &H01AA
        JP      &H01BC
        JP      TRAP
        JP      TRAP
        JP      TRAP
        JP      &H00E3
DEFRT:  RTN
        DB      &HFF,&HFF
        RTN
        DB      &HFF,&HFF
        JP      DEFRT
        JP      POFF
        JP      DEFRT
        JP      DEFRT
        JP      NORMAL_BRK
        JP      DEFRT
        JP      DEFRT
        JP      DEFRT
        JP      DEFRT
        DB      &H12
        DB      &H10
TRAP:   RTNI
POFF:   OFF
        OFF
        OFF
        OFF
        JR      POFF

; ======================================================================
; ENTITY B APPLICATION
; ======================================================================
        ORG     &H0E80

; --------------------------- startup / shell ---------------------------
MAIN:
        CAL     BASE_INIT
        PRE     IX,WS_QN
        LD      $0,8
        ST      $0,(IX+$SX)
        PRE     IX,WS_HN
        ST      $0,(IX+$SX)
        CAL     SHOW_SPLASH
        CAL     SPLASH_WAIT
        JP      TOP_MENU

WARM_ENTRY:
        CAL     BASE_INIT
        JP      TOP_MENU

BASE_INIT:
        PRE     SS,&H0100
        LD      $30,1
        LD      $31,0
        PSR     SZ,0
        PSR     SY,30
        PSR     SX,31
        PST     UA,&H14
; Install the accepted pre-recursion bank-call trampoline in RAM first.
        PRE     IX,RCS_TOP
        PRE     IY,RCS_END-1
        PRE     IZ,RCS
        PST     UA,&H44
        BUP
        PST     UA,&H14

; r005 cursor-context repair.
; The PB-2000C corpus preserves a specific negative/positive pair:
; merely enabling a firmware cursor did not make it visibly blink, while
; establishing the C-ROM application/display environment with
; SYSCLR -> SETLCD -> SET4LN did.  Chapter 06 independently reinforces the
; same application path.  Carry the whole validated capability context,
; not just the CSREN/EDCSR leaf calls.
        PRE     SS,SSPTP
        PRE     US,USPTP
        LDW     $28,SYSCLR
        CAL     SYSCAL
        PST     UA,&H14
        LDW     $28,SETLCD
        CAL     SYSCAL
        PST     UA,&H14
        LDW     $28,SET4LN
        CAL     SYSCAL
        PST     UA,&H14

; Preserve Entity B's established low-level physical display setup after
; the C-ROM geometry transition, matching the accepted pre-recursion order.
        CAL     SCREEN_INIT

; r006: N-input now uses the C-ROM decoded-key path after a raw readiness
; gate.  Establish the same deterministic keyboard mode used by accepted
; pre-recursion application code.
        PST     UA,&H54
        PRE     IX,KEYMD
        ST      $31,(IX+$SX)
        PST     UA,&H14
        RTN

NORMAL_BRK:
; Established BOOT-derived normal BRK exit used by pre-recursion scanners.
        JP      &H0001

SHOW_SPLASH:
        CAL     DISP_CLEAR
        LD      $6,&H00
        PRE     IZ,SPL1
        CAL     ROM32
        LD      $6,&H20
        PRE     IZ,SPL2
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,SPL3
        CAL     ROM32
        LD      $6,&H60
        PRE     IZ,SPL4
        CAL     ROM32
        RTN

SPLASH_WAIT:
; Two distinct stable TM changes: bounded automatic transition, no EXE.
        GST     TM,$8
        GST     TM,$8
        LD      $10,$8
        LD      $11,2
SPW_LOOP:
        CAL     INKEY
        PST     UA,&H14
        AN      $17,$17
        JR      Z,SPW_TIME
        LD      $12,$0
        SBC     $12,KEYBRK
        JP      Z,NORMAL_BRK
        SBC     $12,KEYMENU
        RTN     Z
SPW_TIME:
        GST     TM,$8
        GST     TM,$8
        LD      $12,$8
        SBC     $12,$10
        JR      Z,SPW_LOOP
        LD      $10,$8
        SB      $11,$30
        JR      NZ,SPW_LOOP
        RTN

TOP_MENU:
        CAL     DISP_CLEAR
        LD      $6,&H00
        PRE     IZ,TOP1
        CAL     ROM32
        LD      $6,&H20
        PRE     IZ,TOP2
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,TOP3
        CAL     ROM32
        LD      $6,&H60
        PRE     IZ,TOP4
        CAL     ROM32
TOP_WAIT:
        CAL     WAIT_KEY
        LD      $12,$0
        SBC     $12,KEYBRK
        JP      Z,NORMAL_BRK
        SBC     $12,KEYF1
        JP      Z,Q_ACTION
        SBC     $12,KEYF2
        JP      Z,H_ACTION
        SBC     $12,KEYF3
        JP      Z,VTTEST
        ; MENU at the top menu is already the mandated destination.
        JP      TOP_WAIT

; ---------------------------- Queens shell -----------------------------
Q_ACTION:
        CAL     DISP_CLEAR
        LD      $6,&H00
        PRE     IZ,QACT1
        CAL     ROM32
        PRE     IX,WS_QN
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $6,&H09
        LDW     $12,STRBUF
        CAL     DISP_RAMZ
        LD      $6,&H20
        PRE     IZ,QACT2
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,QACT3
        CAL     ROM32
        LD      $6,&H60
        PRE     IZ,QACT4
        CAL     ROM32
QACT_WAIT:
        CAL     WAIT_KEY
        LD      $12,$0
        SBC     $12,KEYBRK
        JP      Z,NORMAL_BRK
        SBC     $12,KEYMENU
        JP      Z,TOP_MENU
        SBC     $12,KEYF4
        JP      Z,TOP_MENU
        SBC     $12,KEYF1
        JP      Z,Q_VIEW_RUN
        SBC     $12,KEYF2
        JP      Z,Q_COUNT_RUN
        SBC     $12,KEYF3
        JP      Z,Q_NEW_N
        JP      QACT_WAIT

Q_NEW_N:
        LD      $8,0              ; 0 = Queens selector
        CAL     NEW_N
        SBC     $0,1
        JP      Z,TOP_MENU
        JP      Q_ACTION

Q_VIEW_RUN:
        LD      $8,0              ; mode 0 = view
        CAL     Q_RUN
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        JP      NZ,TOP_MENU
        JP      Q_ACTION

Q_COUNT_RUN:
        LD      $8,1              ; mode 1 = count
        CAL     Q_RUN
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        JP      NZ,TOP_MENU
        JP      Q_ACTION

; Q_RUN input $8 mode: 0 view, 1 count.
Q_RUN:
        PHS     $8
        PRE     IX,WS_STOP
        LD      $0,0
        ST      $0,(IX+$SX)
        PRE     IX,WS_QSPIN
        ST      $0,(IX+$SX)
        PRE     IX,WS_QTICK
        ST      $0,(IX+$SX)
        PRE     IX,WS_QCNT
        LDW     $0,0
        STW     $0,(IX+$SX)
        CAL     Q_SEARCH_SCR
        PPS     $8
        PHS     $8
        LD      $9,1              ; recursive row 1
        LD      $8,$9
        CAL     Q_SEARCH
        PPS     $8
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        AN      $8,$8
        JP      Z,Q_VIEW_DONE
        JP      Q_COUNT_DONE

; Recursive row search. Input $8=row (1..N).
Q_SEARCH:
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        LD      $9,1              ; candidate column
QS_CAND:
        PHS     $8
        PHS     $9
        CAL     Q_TICK
        PPS     $9
        PPS     $8
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ

        CAL     Q_SAFE
        AN      $0,$0
        JP      Z,QS_NEXT

; Commit candidate to Q_COLS[row-1].
        LDW     $14,Q_COLS
        LD      $16,$8
        SB      $16,$SY
        AD      $14,$16
        PRE     IX,$14
        ST      $9,(IX+$SX)

; Leaf row means one complete solution.
        PRE     IX,WS_QN
        LD      $10,(IX+$SX)
        LD      $11,$8
        SBC     $11,$10
        JP      Z,QS_FOUND

; Recurse to row+1; preserve parent row/candidate across child.
        PHS     $8
        PHS     $9
        AD      $8,$SY
        CAL     Q_SEARCH
        PPS     $9
        PPS     $8
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        JP      QS_NEXT

QS_FOUND:
        PHS     $8
        PHS     $9
        CAL     Q_FOUND
        PPS     $9
        PPS     $8
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ

QS_NEXT:
        AD      $9,$SY
        PRE     IX,WS_QN
        LD      $10,(IX+$SX)
        LD      $11,$9
        SBC     $11,$10
        JP      C,QS_CAND
        JP      Z,QS_CAND
        RTN

; Q_SAFE input row $8, candidate $9. Output $0=1 safe, 0 attacked.
Q_SAFE:
        LD      $10,1             ; previous row
QSF_LOOP:
        LD      $11,$10
        SBC     $11,$8
        JP      Z,QSF_YES         ; no previous rows remain

        LDW     $14,Q_COLS
        LD      $16,$10
        SB      $16,$SY
        AD      $14,$16
        PRE     IX,$14
        LD      $12,(IX+$SX)      ; previous column

; Same column.
        LD      $13,$12
        SBC     $13,$9
        JP      Z,QSF_NO

; Same descending diagonal: prev_col+prev_row == cand+row.
        LD      $13,$12
        AD      $13,$10
        LD      $14,$9
        AD      $14,$8
        SBC     $13,$14
        JP      Z,QSF_NO

; Same ascending diagonal, modulo byte arithmetic is exact in range 1..10.
        LD      $13,$12
        SB      $13,$10
        LD      $14,$9
        SB      $14,$8
        SBC     $13,$14
        JP      Z,QSF_NO

        AD      $10,$SY
        JP      QSF_LOOP
QSF_YES:
        LD      $0,1
        RTN
QSF_NO:
        LD      $0,0
        RTN

Q_TICK:
; Service/update every 256 candidate attempts.  This throttles display work.
        PRE     IX,WS_QTICK
        LD      $0,(IX+$SX)
        AD      $0,$SY
        ST      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        CAL     Q_PROGRESS
        RTN

Q_FOUND:
; Increment sequential solution count.
        PRE     IX,WS_QCNT
        LDW     $20,(IX+$SX)
        ADW     $20,$SY
        STW     $20,(IX+$SX)
        CAL     Q_PROGRESS

; Determine run mode from the caller-owned stack-independent flag in $8 is
; not safe after helper calls; Q_RUN mode is mirrored transiently below.
; View/count selection is encoded by WS_NDIG during Q_RUN only.
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        CAL     Q_SOL_PAGE
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        CAL     Q_SEARCH_DRAW
        RTN

; Search screen.  WS_NDIG is reused as run-mode byte: 0 view, 1 count.
Q_SEARCH_SCR:
        PRE     IX,WS_NDIG
        ST      $8,(IX+$SX)
Q_SEARCH_DRAW:
        CAL     DISP_CLEAR
        LD      $6,&H00
        PRE     IZ,QSR1
        CAL     ROM32
        PRE     IX,WS_QN
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $6,&H10
        LDW     $12,STRBUF
        CAL     DISP_RAMZ
        LD      $6,&H20
        PRE     IZ,QSR2
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,QSR3
        CAL     ROM32
        LD      $6,&H60
        PRE     IZ,QSR4
        CAL     ROM32
        CAL     Q_PROGRESS
        RTN

Q_PROGRESS:
; NF-05: intentionally dirty-region only while the search screen is active.
; No DISP_CLEAR here: update fixed-width count + one spinner cell, then poll.
; Full redraw remains confined to Q_SEARCH_DRAW on screen/mode transition.
; Count at row2 columns 7..10 (zero-based position 0x26).
        PRE     IX,WS_QCNT
        LDW     $20,(IX+$SX)
        CAL     BUF_DEC4
        LD      $6,&H26
        LDW     $12,STRBUF
        CAL     DISP_RAMZ

; Rotating indicator at row3 column 6 (zero-based position 0x45).
        PRE     IX,WS_QSPIN
        LD      $2,(IX+$SX)
        LD      $16,&H7C          ; |
        AN      $2,$2
        JR      Z,QP_SPIN
        SBC     $2,1
        JR      Z,QP_S1
        SBC     $2,2
        JR      Z,QP_S2
        LD      $16,&H5C          ; backslash
        JR      QP_SPIN
QP_S1:  LD      $16,&H2F          ; /
        JR      QP_SPIN
QP_S2:  LD      $16,&H2D          ; -
QP_SPIN:
        LD      $6,&H45
        CAL     PUTC
        PRE     IX,WS_QSPIN
        LD      $2,(IX+$SX)
        AD      $2,$SY
        AN      $2,&H03
        ST      $2,(IX+$SX)

; Cooperative MENU/BRK service point.
        CAL     POLL_CTRL
        SBC     $0,2
        JP      Z,NORMAL_BRK
        SBC     $0,1
        JR      NZ,QP_RET
        PRE     IX,WS_STOP
        LD      $0,1
        ST      $0,(IX+$SX)
QP_RET: RTN

Q_SOL_PAGE:
        CAL     VT_CLEAR
; Line 1: title, N and sequential solution number. Cols 1..2 stay clear.
        LD      $8,1
        LDW     $10,4
        PRE     IZ,VQ_TITLE
        CAL     VT_ROM
        PRE     IX,WS_QN
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $8,1
        LDW     $10,15
        LDW     $12,STRBUF
        CAL     VT_WRITE
        LD      $8,1
        LDW     $10,18
        PRE     IZ,VQ_SOL
        CAL     VT_ROM
        PRE     IX,WS_QCNT
        LDW     $20,(IX+$SX)
        CAL     BUF_DEC4
        LD      $8,1
        LDW     $10,22
        LDW     $12,STRBUF
        CAL     VT_WRITE

; Complete N x N board on virtual lines 3..12, starting column 3.
        LD      $18,1             ; board row
VQB_ROW:
        PRE     IX,WS_QN
        LD      $19,(IX+$SX)
        LD      $0,$18
        SBC     $0,$19
        JR      C,VQB_BUILD
        JR      Z,VQB_BUILD
        JP      VQB_DONE
VQB_BUILD:
        LDW     $22,STRBUF         ; output pointer kept in main-register pair
        LD      $20,1             ; board column
VQB_COL:
        LDW     $14,Q_COLS
        LD      $16,$18
        SB      $16,$SY
        AD      $14,$16
        PRE     IX,$14
        LD      $17,(IX+$SX)
        LD      $16,&H2E          ; .
        LD      $0,$20
        SBC     $0,$17
        JR      NZ,VQB_STORE
        LD      $16,&H51          ; Q
VQB_STORE:
        PRE     IX,$22
        ST      $16,(IX+$SX)
        ADW     $22,$SY
        AD      $20,$SY
        PRE     IX,WS_QN
        LD      $21,(IX+$SX)
        LD      $0,$20
        SBC     $0,$21
        JR      C,VQB_COL
        JR      Z,VQB_COL
        PRE     IX,$22
        LD      $16,0
        ST      $16,(IX+$SX)
        LD      $8,$18
        AD      $8,2              ; virtual line 3 + row-1
        LDW     $10,4
        LDW     $12,STRBUF
        PHS     $18
        CAL     VT_WRITE
        PPS     $18
        AD      $18,$SY
        JP      VQB_ROW
VQB_DONE:
        LD      $8,24
        LDW     $10,4
        PRE     IZ,VQ_NEXT
        CAL     VT_ROM
        CAL     VT_VIEW
        SBC     $0,2
        JP      Z,NORMAL_BRK
        SBC     $0,1
        JR      NZ,VQB_RET
        PRE     IX,WS_STOP
        LD      $0,1
        ST      $0,(IX+$SX)
VQB_RET:RTN

Q_VIEW_DONE:
        CAL     Q_DONE_PAGE
        RTN

Q_COUNT_DONE:
        CAL     Q_DONE_PAGE
        RTN

Q_DONE_PAGE:
        CAL     VT_CLEAR
        LD      $8,1
        LDW     $10,4
        PRE     IZ,VQ_DONE
        CAL     VT_ROM
        LD      $8,3
        LDW     $10,4
        PRE     IZ,VQ_NLAB
        CAL     VT_ROM
        PRE     IX,WS_QN
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $8,3
        LDW     $10,6
        LDW     $12,STRBUF
        CAL     VT_WRITE
        LD      $8,5
        LDW     $10,4
        PRE     IZ,VQ_TOT
        CAL     VT_ROM
        PRE     IX,WS_QCNT
        LDW     $20,(IX+$SX)
        CAL     BUF_DEC4
        LD      $8,5
        LDW     $10,10
        LDW     $12,STRBUF
        CAL     VT_WRITE
        LD      $8,24
        LDW     $10,4
        PRE     IZ,VQ_BACK
        CAL     VT_ROM
        CAL     VT_VIEW
        SBC     $0,2
        JP      Z,NORMAL_BRK
        SBC     $0,1
        JR      NZ,QDP_RET
        PRE     IX,WS_STOP
        LD      $0,1
        ST      $0,(IX+$SX)
QDP_RET:RTN

; ----------------------------- Hanoi shell -----------------------------
H_ACTION:
        CAL     DISP_CLEAR
        LD      $6,&H00
        PRE     IZ,HACT1
        CAL     ROM32
        PRE     IX,WS_HN
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $6,&H08
        LDW     $12,STRBUF
        CAL     DISP_RAMZ
        LD      $6,&H20
        PRE     IZ,HACT2
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,HACT3
        CAL     ROM32
        LD      $6,&H60
        PRE     IZ,HACT4
        CAL     ROM32
HACT_WAIT:
        CAL     WAIT_KEY
        LD      $12,$0
        SBC     $12,KEYBRK
        JP      Z,NORMAL_BRK
        SBC     $12,KEYMENU
        JP      Z,TOP_MENU
        SBC     $12,KEYF4
        JP      Z,TOP_MENU
        SBC     $12,KEYF1
        JP      Z,H_RUN
        SBC     $12,KEYF2
        JP      Z,H_NEW_N
        JP      HACT_WAIT

H_NEW_N:
        LD      $8,1              ; 1 = Hanoi selector
        CAL     NEW_N
        SBC     $0,1
        JP      Z,TOP_MENU
        JP      H_ACTION

H_RUN:
        PRE     IX,WS_STOP
        LD      $0,0
        ST      $0,(IX+$SX)
        PRE     IX,WS_HMOVE
        LDW     $0,0
        STW     $0,(IX+$SX)
        CAL     H_START_PAGE

; H_REC(N,'A','B','C')
        PRE     IX,WS_HN
        LD      $8,(IX+$SX)
        LD      $9,&H41
        LD      $10,&H42
        LD      $11,&H43
        CAL     H_REC
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        JP      NZ,TOP_MENU

; Final partial move page, then a separate completion page.
        PRE     IX,WS_HPGCNT
        LD      $0,(IX+$SX)
        AN      $0,$0
        JR      Z,H_SHOW_DONE
        PRE     IX,WS_HMOVE
        LDW     $0,(IX+$SX)
        PRE     IX,WS_HLAST
        STW     $0,(IX+$SX)
        LD      $8,1              ; final page flag
        CAL     H_PAGE_HEAD
        CAL     VT_VIEW
        SBC     $0,2
        JP      Z,NORMAL_BRK
        SBC     $0,1
        JP      Z,TOP_MENU
H_SHOW_DONE:
        CAL     H_DONE_PAGE
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        JP      NZ,TOP_MENU
        JP      H_ACTION

; Recursive minimal legal three-peg Hanoi.
; input: $8=n, $9=source, $10=aux, $11=dest.
H_REC:
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ
        AN      $8,$8
        RTN     Z

; First recursion: n-1, source, dest, aux.
        PHS     $8
        PHS     $9
        PHS     $10
        PHS     $11
        SB      $8,$SY
        LD      $12,$10
        LD      $10,$11
        LD      $11,$12
        CAL     H_REC
        PPS     $11
        PPS     $10
        PPS     $9
        PPS     $8
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ

; Emit move n:source>dest.
        PHS     $8
        PHS     $9
        PHS     $10
        PHS     $11
        CAL     H_EMIT
        PPS     $11
        PPS     $10
        PPS     $9
        PPS     $8
        PRE     IX,WS_STOP
        LD      $0,(IX+$SX)
        AN      $0,$0
        RTN     NZ

; Second recursion: n-1, aux, source, dest.
        PHS     $8
        PHS     $9
        PHS     $10
        PHS     $11
        SB      $8,$SY
        LD      $12,$9
        LD      $9,$10
        LD      $10,$12
        CAL     H_REC
        PPS     $11
        PPS     $10
        PPS     $9
        PPS     $8
        RTN

H_START_PAGE:
        CAL     VT_CLEAR
        PRE     IX,WS_HPGCNT
        LD      $0,0
        ST      $0,(IX+$SX)
        PRE     IX,WS_HLINE
        LD      $0,2
        ST      $0,(IX+$SX)
        PRE     IX,WS_HSLOT
        LD      $0,0
        ST      $0,(IX+$SX)
        RTN

; H_EMIT input preserved by caller: $8=disk, $9=source, $11=dest.
H_EMIT:
; Increment global move number.
        PRE     IX,WS_HMOVE
        LDW     $20,(IX+$SX)
        ADW     $20,$SY
        STW     $20,(IX+$SX)

; First move on page captures range start.
        PRE     IX,WS_HPGCNT
        LD      $0,(IX+$SX)
        AN      $0,$0
        JR      NZ,HE_BUILD
        PRE     IX,WS_HFIRST
        STW     $20,(IX+$SX)
HE_BUILD:
; Build exactly seven visible chars plus NUL: DD:S>D<space>.
        PRE     IX,STRBUF
        LD      $16,&H30
        LD      $17,$8
        SBC     $17,10
        JR      NZ,HE_D1
        LD      $16,&H31
HE_D1:  STI     $16,(IX+$SX)
        LD      $16,$8
        SBC     $16,10
        JR      NZ,HE_D2A
        LD      $16,&H30
        JR      HE_D2B
HE_D2A: AD      $16,&H30
HE_D2B: STI     $16,(IX+$SX)
        LD      $16,&H3A
        STI     $16,(IX+$SX)
        STI     $9,(IX+$SX)
        LD      $16,&H3E
        STI     $16,(IX+$SX)
        STI     $11,(IX+$SX)
        LD      $16,&H20
        STI     $16,(IX+$SX)
        LD      $16,0
        STI     $16,(IX+$SX)

; VT line and field position: cols 3,10,17,24; lines 2..23.
        PRE     IX,WS_HLINE
        LD      $8,(IX+$SX)
        PRE     IX,WS_HSLOT
        LD      $2,(IX+$SX)
        LDW     $10,3
        AN      $2,$2
        JR      Z,HE_POS
        LDW     $4,7
HE_POSLP:
        ADW     $10,$4
        SB      $2,$SY
        JR      NZ,HE_POSLP
HE_POS:
        LDW     $12,STRBUF
        CAL     VT_WRITE

; Advance page slot.
        PRE     IX,WS_HPGCNT
        LD      $0,(IX+$SX)
        AD      $0,$SY
        ST      $0,(IX+$SX)
        PRE     IX,WS_HSLOT
        LD      $2,(IX+$SX)
        AD      $2,$SY
        SBC     $2,4
        JR      NZ,HE_SAVESLOT
        LD      $2,0
        ST      $2,(IX+$SX)
        PRE     IX,WS_HLINE
        LD      $3,(IX+$SX)
        AD      $3,$SY
        ST      $3,(IX+$SX)
        JR      HE_PAGECHK
HE_SAVESLOT:
        ST      $2,(IX+$SX)

HE_PAGECHK:
        PRE     IX,WS_HPGCNT
        LD      $0,(IX+$SX)
        SBC     $0,88
        JR      NZ,HE_POLL

; Full page is necessarily non-final because 2^N-1 is odd and 88 is even.
        PRE     IX,WS_HMOVE
        LDW     $0,(IX+$SX)
        PRE     IX,WS_HLAST
        STW     $0,(IX+$SX)
        LD      $8,0
        CAL     H_PAGE_HEAD
        CAL     VT_VIEW
        SBC     $0,2
        JP      Z,NORMAL_BRK
        SBC     $0,1
        JR      NZ,HE_NEXTPG
        PRE     IX,WS_STOP
        LD      $0,1
        ST      $0,(IX+$SX)
        RTN
HE_NEXTPG:
        CAL     H_START_PAGE

HE_POLL:
        CAL     POLL_CTRL
        SBC     $0,2
        JP      Z,NORMAL_BRK
        SBC     $0,1
        JR      NZ,HE_RET
        PRE     IX,WS_STOP
        LD      $0,1
        ST      $0,(IX+$SX)
HE_RET: RTN

; H_PAGE_HEAD input $8: 0 non-final, 1 final.
H_PAGE_HEAD:
        PHS     $8
        LD      $8,1
        LDW     $10,4
        PRE     IZ,VH_TITLE
        CAL     VT_ROM
        PRE     IX,WS_HN
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $8,1
        LDW     $10,12
        LDW     $12,STRBUF
        CAL     VT_WRITE
        LD      $8,1
        LDW     $10,15
        PRE     IZ,VH_MOVES
        CAL     VT_ROM
        PRE     IX,WS_HFIRST
        LDW     $20,(IX+$SX)
        CAL     BUF_DEC4
        LD      $8,1
        LDW     $10,21
        LDW     $12,STRBUF
        CAL     VT_WRITE
        LD      $8,1
        LDW     $10,25
        PRE     IZ,VH_DASH
        CAL     VT_ROM
        PRE     IX,WS_HLAST
        LDW     $20,(IX+$SX)
        CAL     BUF_DEC4
        LD      $8,1
        LDW     $10,26
        LDW     $12,STRBUF
        CAL     VT_WRITE
        PPS     $8
        AN      $8,$8
        JR      NZ,HPP_FINAL
        LD      $8,24
        LDW     $10,4
        PRE     IZ,VH_NEXT
        CAL     VT_ROM
        RTN
HPP_FINAL:
        LD      $8,24
        LDW     $10,4
        PRE     IZ,VH_FINAL
        CAL     VT_ROM
        RTN

H_DONE_PAGE:
        CAL     VT_CLEAR
        LD      $8,1
        LDW     $10,4
        PRE     IZ,VH_DONE
        CAL     VT_ROM
        LD      $8,3
        LDW     $10,4
        PRE     IZ,VQ_NLAB
        CAL     VT_ROM
        PRE     IX,WS_HN
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $8,3
        LDW     $10,6
        LDW     $12,STRBUF
        CAL     VT_WRITE
        LD      $8,5
        LDW     $10,4
        PRE     IZ,VH_TOTAL
        CAL     VT_ROM
        PRE     IX,WS_HMOVE
        LDW     $20,(IX+$SX)
        CAL     BUF_DEC4
        LD      $8,5
        LDW     $10,16
        LDW     $12,STRBUF
        CAL     VT_WRITE
        LD      $8,24
        LDW     $10,4
        PRE     IZ,VQ_BACK
        CAL     VT_ROM
        CAL     VT_VIEW
        SBC     $0,2
        JP      Z,NORMAL_BRK
        SBC     $0,1
        JR      NZ,HDP_RET
        PRE     IX,WS_STOP
        LD      $0,1
        ST      $0,(IX+$SX)
HDP_RET:RTN

; ----------------------------- new N input -----------------------------
; input $8 selector: 0 Queens, 1 Hanoi
; return $0: 0 accepted/back-to-action, 1 MENU/top.
NEW_N:
        PHS     $8
        CAL     DISP_CLEAR
        LD      $6,&H00
        PRE     IZ,NN1
        CAL     ROM32
        LD      $6,&H20
        PRE     IZ,NN2
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,NN3
        CAL     ROM32
        LD      $6,&H60
        PRE     IZ,NN4
        CAL     ROM32
        PRE     IX,WS_NEWT
        LD      $0,0
        ST      $0,(IX+$SX)
        PRE     IX,WS_NDIG
        ST      $0,(IX+$SX)
        CAL     NN_DRAW
NN_LOOP:
        CAL     NN_KEYWAIT
        LD      $12,$0
        SBC     $12,KEYBRK
        JP      Z,NN_BRK
        SBC     $12,KEYMENU
        JP      Z,NN_MENU
        SBC     $12,KEYF4
        JP      Z,NN_MENU
        SBC     $12,KEYBS
        JP      Z,NN_BS
        SBC     $12,KEYEXE
        JP      Z,NN_ACCEPT

; Decimal digits only.
        LD      $13,$12
        SBC     $13,&H30
        JR      C,NN_LOOP
        LD      $13,$12
        SBC     $13,&H3A
        JP      NC,NN_LOOP
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        SBC     $0,2
        JP      NC,NN_LOOP

; value = value*10 + digit, bounded naturally by two typed digits.
        PRE     IX,WS_NEWT
        LD      $0,(IX+$SX)
        LD      $2,$0
        BIU     $0               ; *2
        BIU     $0               ; *4
        AD      $0,$2            ; *5
        BIU     $0               ; *10
        LD      $2,$12
        SB      $2,&H30
        AD      $0,$2
        ST      $0,(IX+$SX)
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        AD      $0,$SY
        ST      $0,(IX+$SX)
        CAL     NN_DRAW
        JP      NN_LOOP

NN_BS:
; For at most two digits, recompute from the surviving first digit display.
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        AN      $0,$0
        JP      Z,NN_LOOP
        SBC     $0,1
        JR      Z,NN_CLEAR
; two digits -> retain tens = value / 10 by repeated subtraction.
        PRE     IX,WS_NEWT
        LD      $20,(IX+$SX)
        LD      $21,0
NN_DIV10:
        SBC     $20,10
        JR      C,NN_DIVDONE
        SB      $20,10
        AD      $21,$SY
        JR      NN_DIV10
NN_DIVDONE:
        LD      $0,$21
        ST      $0,(IX+$SX)
        PRE     IX,WS_NDIG
        LD      $0,1
        ST      $0,(IX+$SX)
        CAL     NN_DRAW
        JP      NN_LOOP
NN_CLEAR:
        PRE     IX,WS_NEWT
        LD      $0,0
        ST      $0,(IX+$SX)
        PRE     IX,WS_NDIG
        ST      $0,(IX+$SX)
        CAL     NN_DRAW
        JP      NN_LOOP

NN_ACCEPT:
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        AN      $0,$0
        JP      Z,NN_BAD
        PRE     IX,WS_NEWT
        LD      $0,(IX+$SX)
        AN      $0,$0
        JP      Z,NN_BAD
        LD      $2,$0
        SBC     $2,11
        JP      NC,NN_BAD
        PPS     $8
        AN      $8,$8
        JR      NZ,NN_STOREH
        PRE     IX,WS_QN
        ST      $0,(IX+$SX)
        CAL     CUR_OFF
        LD      $0,0
        RTN
NN_STOREH:
        PRE     IX,WS_HN
        ST      $0,(IX+$SX)
        CAL     CUR_OFF
        LD      $0,0
        RTN
NN_BAD:
; Keep the input field visible; use row 2 for rejection feedback.
        LD      $6,&H20
        PRE     IZ,NN_BADROW
        CAL     ROM32
        JP      NN_LOOP
NN_MENU:
        CAL     CUR_OFF
        PPS     $8
        LD      $0,1
        RTN
NN_BRK:
        CAL     CUR_OFF
        JP      NORMAL_BRK

; r007 native N-editor key wait.
; Piotr Piatek's machine-level note identifies CRTKY itself as the owner of
; cursor blinking: while it blocks for a key it periodically calls &H0364.
; Therefore do not pre-scan the keyboard here.  BRK is handled through the
; language-card vector at &H0DAA, now restored to NORMAL_BRK.
NN_KEYWAIT:
        LDW     $28,CRTKY
        CAL     SYSCAL
        PST     UA,&H14
        RTN

NN_DRAW:
; Restore instruction row, redraw the bounded input field, and position the
; platform cursor immediately after the number actually typed.
        LD      $6,&H20
        PRE     IZ,NN2
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,BLANK32
        CAL     ROM32
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        AN      $0,$0
        JR      Z,NN_SETCUR
        PRE     IX,WS_NEWT
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        SBC     $0,1
        JR      NZ,NN_DRAWTWO
        LD      $6,&H4F
        LDW     $12,STRBUF+1
        CAL     DISP_RAMZ
        JR      NN_SETCUR
NN_DRAWTWO:
        LD      $6,&H4F
        LDW     $12,STRBUF
        CAL     DISP_RAMZ
NN_SETCUR:
        PRE     IX,WS_NDIG
        LD      $0,(IX+$SX)
        LD      $6,&H4F
        AD      $6,$0
        PST     UA,&H54
        PRE     IX,EDCSR
        ST      $6,(IX+$SX)
        PST     UA,&H14
        CAL     CUR_ON
        RTN

CUR_ON:
        LDW     $28,CSREN
        CAL     SYSCAL
        PST     UA,&H14
        RTN

CUR_OFF:
        LDW     $28,CSRDIS
        CAL     SYSCAL
        PST     UA,&H14
        RTN

; ------------------------------ VTTEST ---------------------------------
VTTEST:
        CAL     VT_CLEAR
        LD      $18,1
VTT_LOOP:
        PHS     $18
        LD      $20,$18
        CAL     BUF_DEC2
        PPS     $18
; Append a Lorem-style suffix after the two digits in STRBUF.
        PRE     IX,STRBUF+2
        PRE     IZ,VTT_SUFFIX
VTT_COPY:
        LDI     $0,(IZ+$SX)
        STI     $0,(IX+$SX)
        AN      $0,$0
        JR      NZ,VTT_COPY
        LD      $8,$18
; NF-01A: col3 remains blank so the fixed cols1..2 overlay reads "VT 01 ...".
; This is the observable-resolution of the candidate NFR's indent arithmetic.
        LDW     $10,4
        LDW     $12,STRBUF
        PHS     $18
        CAL     VT_WRITE
        PPS     $18
        AD      $18,$SY
        LD      $0,$18
        SBC     $0,25
        JR      C,VTT_LOOP
        CAL     VT_VIEW
        SBC     $0,2
        JP      Z,NORMAL_BRK
        JP      TOP_MENU          ; Q and MENU both return to top here

; ======================================================================
; SHARED VT LIBRARY - private backing storage, public services only.
; ======================================================================

VT_CLEAR:
        PRE     IX,VT_BASE
        LDW     $20,VT_SIZE
        LD      $0,&H20
VTC_LOOP:
        STI     $0,(IX+$SX)
        SBW     $20,$SY
        JR      NZ,VTC_LOOP
        RTN

; VT_WRITE(line,column,string)
;   input $8      = conceptual line (1..24)
;         $10/$11 = conceptual signed column
;         $12/$13 = NUL-terminated string in ordinary bank-1 RAM
;   output $0 = 00 all chars stored, 01 one or more chars clipped/not stored
;   fixed-position overwrite, no wrap.
VT_WRITE:
        LD      $0,0
; Empty string succeeds vacuously even if line is outside the surface.
        PRE     IX,$12
        LD      $4,(IX+$SX)
        AN      $4,$4
        RTN     Z

; Validate line 1..24.
        AN      $8,$8
        JP      Z,VTW_BADLINE
        LD      $2,$8
        SBC     $2,25
        JP      NC,VTW_BADLINE

; Row base = VT_BASE + (line-1)*32.
        LDW     $14,VT_BASE
        LD      $16,$8
        SB      $16,$SY
        JR      Z,VTW_LOOP
        LDW     $18,32
VTW_ROW:
        ADW     $14,$18
        SB      $16,$SY
        JR      NZ,VTW_ROW

VTW_LOOP:
        PRE     IX,$12
        LD      $4,(IX+$SX)
        AN      $4,$4
        RTN     Z
        ADW     $12,$SY

; Signed negative columns are left-clipped.
        LD      $5,$11
        AN      $5,&H80
        JP      NZ,VTW_CLIP
        LDW     $2,$10
        LDW     $6,1
        SBCW    $2,$6
        JP      C,VTW_CLIP
        LDW     $2,$10
        LDW     $6,33
        SBCW    $2,$6
        JP      NC,VTW_CLIP

; Store at rowbase + (column-1).
        LDW     $2,$10
        SBW     $2,$SY
        ADW     $2,$14
        PRE     IX,$2
        ST      $4,(IX+$SX)
        JP      VTW_NEXT
VTW_CLIP:
        LD      $0,1
VTW_NEXT:
        ADW     $10,$SY
        JP      VTW_LOOP

VTW_BADLINE:
        LD      $0,1
        RTN

; Internal convenience: copy ROM NUL string to STRBUF, then call VT_WRITE.
; All VT mutation still occurs only through VT_WRITE.
VT_ROM:
        CAL     COPY_ROM
        LDW     $12,STRBUF
        JP      VT_WRITE

; VT_VIEW returns: 00 Q, 01 MENU, 02 BRK.
VT_VIEW:
        PRE     IX,WS_VTOP
        LD      $0,1
        ST      $0,(IX+$SX)
VTV_LOOP:
        CAL     VT_RENDER
        CAL     WAIT_KEY
        LD      $12,$0
        SBC     $12,KEYQ
        JR      Z,VTV_Q
        SBC     $12,KEYMENU
        JR      Z,VTV_MENU
        SBC     $12,KEYBRK
        JR      Z,VTV_BRK
        SBC     $12,KEYUP
        JP      Z,VTV_UP
        SBC     $12,KEYDN
        JP      Z,VTV_DOWN
        JP      VTV_LOOP
VTV_Q:  LD      $0,0
        RTN
VTV_MENU:
        LD      $0,1
        RTN
VTV_BRK:
        LD      $0,2
        RTN
VTV_UP:
        PRE     IX,WS_VTOP
        LD      $0,(IX+$SX)
        SBC     $0,1
        JP      Z,VTV_LOOP
        PRE     IX,WS_VTOP
        LD      $0,(IX+$SX)
        SB      $0,$SY
        ST      $0,(IX+$SX)
        JP      VTV_LOOP
VTV_DOWN:
        PRE     IX,WS_VTOP
        LD      $0,(IX+$SX)
        SBC     $0,21
        JP      Z,VTV_LOOP
        PRE     IX,WS_VTOP
        LD      $0,(IX+$SX)
        AD      $0,$SY
        ST      $0,(IX+$SX)
        JP      VTV_LOOP

VT_RENDER:
        PRE     IX,WS_VTOP
        LD      $8,(IX+$SX)
        CAL     VT_ROWADDR
        LD      $6,&H00
        CAL     DRAW_RAM32
        PRE     IX,WS_VTOP
        LD      $8,(IX+$SX)
        AD      $8,1
        CAL     VT_ROWADDR
        LD      $6,&H20
        CAL     DRAW_RAM32
        PRE     IX,WS_VTOP
        LD      $8,(IX+$SX)
        AD      $8,2
        CAL     VT_ROWADDR
        LD      $6,&H40
        CAL     DRAW_RAM32
        PRE     IX,WS_VTOP
        LD      $8,(IX+$SX)
        AD      $8,3
        CAL     VT_ROWADDR
        LD      $6,&H60
        CAL     DRAW_RAM32

; Physical-only overlays: row1 cols1..2 = VT; row4 cols31..32 = top line.
        LD      $6,&H00
        LD      $16,&H56
        CAL     PUTC
        LD      $16,&H54
        CAL     PUTC
        PRE     IX,WS_VTOP
        LD      $20,(IX+$SX)
        CAL     BUF_DEC2
        LD      $6,&H7E
        LDW     $12,STRBUF
        CAL     DISP_RAMZ
        RTN

; input $8 line 1..24, output $2/$3 address of first cell.
VT_ROWADDR:
        LDW     $2,VT_BASE
        LD      $4,$8
        SB      $4,$SY
        RTN     Z
        LDW     $6,32
VTRA_LOOP:
        ADW     $2,$6
        SB      $4,$SY
        JR      NZ,VTRA_LOOP
        RTN

; ======================================================================
; KEYBOARD / DISPLAY HELPERS
; ======================================================================
WAIT_KEY:
WK_PRESS:
        CAL     INKEY
        PST     UA,&H14
        AN      $17,$17
        JR      Z,WK_PRESS
        LD      $12,$0
        PHS     $12
WK_RELEASE:
        CAL     INKEY
        PST     UA,&H14
        AN      $17,$17
        JR      NZ,WK_RELEASE
        PPS     $12
        LD      $0,$12
        RTN

; Nonblocking control poll. Return 0 none/other, 1 MENU, 2 BRK.
POLL_CTRL:
        CAL     INKEY
        PST     UA,&H14
        AN      $17,$17
        JR      Z,PC_NONE
        LD      $12,$0
        SBC     $12,KEYBRK
        JR      Z,PC_BRK
        SBC     $12,KEYMENU
        JR      Z,PC_MENU
        SBC     $12,KEYF4
        JR      Z,PC_MENU
        JP      PC_OTHER
; Other keys are ignored and consumed through release so they cannot leak
; into a later blocking viewer prompt.
PC_OTHER:
PC_REL:
        CAL     INKEY
        PST     UA,&H14
        AN      $17,$17
        JR      NZ,PC_REL
PC_NONE:LD      $0,0
        RTN
PC_MENU:LD      $0,1
        RTN
PC_BRK: LD      $0,2
        RTN

SCREEN_INIT:
        PST     UA,&H14
        CAL     OFFCHK
        PPO     &HC0
        LDW     $0,&H12B5
SI_DELAY:
        SBW     $0,$SY
        JR      NZ,SI_DELAY
        CAL     &H02D4
        PPO     &HC3
        LD      $0,&H0C
        LDW     $1,&H3000
        STLM    $0,3
        LD      $6,$SX
        LD      $8,128
        CAL     &H018D
        CAL     &H0304
        CAL     &H0306
        RTN

PUTC:
        LD      $7,$16
        LD      $0,$7
        DIU     $7
        DID     $0
        OR      $7,$SZ
        CAL     &H0197
        RTN

ROM32:
        LD      $20,32
R32_LOOP:
        LDI     $16,(IZ+$SX)
        PHS     $20
        CAL     PUTC
        PPS     $20
        SB      $20,$SY
        JR      NZ,R32_LOOP
        RTN

DISP_CLEAR:
        LD      $6,&H00
        PRE     IZ,BLANK32
        CAL     ROM32
        LD      $6,&H20
        PRE     IZ,BLANK32
        CAL     ROM32
        LD      $6,&H40
        PRE     IZ,BLANK32
        CAL     ROM32
        LD      $6,&H60
        PRE     IZ,BLANK32
        CAL     ROM32
        RTN

; Display NUL RAM string at physical cursor $6. Pointer input $12/$13.
DISP_RAMZ:
        PRE     IX,WS_DPTR
        STW     $12,(IX+$SX)
DRZ_LOOP:
        PRE     IX,WS_DPTR
        LDW     $2,(IX+$SX)
        PRE     IX,$2
        LD      $16,(IX+$SX)
        AN      $16,$16
        RTN     Z
        ADW     $2,$SY
        PRE     IX,WS_DPTR
        STW     $2,(IX+$SX)
        CAL     PUTC
        JP      DRZ_LOOP

; Draw exactly 32 RAM bytes. Input pointer $2/$3, physical cursor $6.
DRAW_RAM32:
        PRE     IX,WS_DPTR
        STW     $2,(IX+$SX)
        PRE     IX,WS_DIDX
        LD      $0,0
        ST      $0,(IX+$SX)
DR32_LOOP:
        PRE     IX,WS_DPTR
        LDW     $2,(IX+$SX)
        PRE     IX,$2
        LD      $16,(IX+$SX)
        CAL     PUTC
        PRE     IX,WS_DPTR
        LDW     $2,(IX+$SX)
        ADW     $2,$SY
        STW     $2,(IX+$SX)
        PRE     IX,WS_DIDX
        LD      $0,(IX+$SX)
        AD      $0,$SY
        ST      $0,(IX+$SX)
        SBC     $0,32
        JR      NZ,DR32_LOOP
        RTN

; ROM NUL string -> STRBUF.  Caller guarantees <=63 visible chars.
COPY_ROM:
        PRE     IX,STRBUF
CR_LOOP:
        LDI     $0,(IZ+$SX)
        STI     $0,(IX+$SX)
        AN      $0,$0
        JR      NZ,CR_LOOP
        RTN

; Zero-padded decimal 00..99. Input byte $20, output STRBUF NUL string.
BUF_DEC2:
        PRE     IX,STRBUF
        LD      $16,&H30
        LD      $18,$20
BD2_TEN:
        SBC     $18,10
        JR      C,BD2_TDONE
        SB      $18,10
        AD      $16,$SY
        JR      BD2_TEN
BD2_TDONE:
        STI     $16,(IX+$SX)
        LD      $16,$18
        AD      $16,&H30
        STI     $16,(IX+$SX)
        LD      $16,0
        STI     $16,(IX+$SX)
        RTN

; Zero-padded decimal 0000..9999. Input word $20/$21.
BUF_DEC4:
        PRE     IX,STRBUF
        LD      $16,&H30
BD4_1000:
        LDW     $24,1000
        SBCW    $20,$24
        JR      C,BD4_1DONE
        SBW     $20,$24
        AD      $16,$SY
        JR      BD4_1000
BD4_1DONE:
        STI     $16,(IX+$SX)
        LD      $16,&H30
BD4_100:
        LDW     $24,100
        SBCW    $20,$24
        JR      C,BD4_2DONE
        SBW     $20,$24
        AD      $16,$SY
        JR      BD4_100
BD4_2DONE:
        STI     $16,(IX+$SX)
        LD      $16,&H30
BD4_10:
        LDW     $24,10
        SBCW    $20,$24
        JR      C,BD4_3DONE
        SBW     $20,$24
        AD      $16,$SY
        JR      BD4_10
BD4_3DONE:
        STI     $16,(IX+$SX)
        LD      $16,$20
        AD      $16,&H30
        STI     $16,(IX+$SX)
        LD      $16,0
        STI     $16,(IX+$SX)
        RTN

; ======================================================================
; ROM TEXT
; ======================================================================
; Every physical-screen row below is exactly 32 characters.
SPL1:   DB "         Xandrian Labs          "
SPL2:   DB "           CS617 CH12           "
SPL3:   DB "        Recursion Angel         "
SPL4:   DB "            Entity B            "
; r004 parity closure: NFR rev 2 requires top-menu rows 2 and 3 blank.
TOP1:   DB "CS617 CH12 - Recursion Angel    "
TOP2:   DB "                                "
TOP3:   DB "                                "
TOP4:   DB "[queens][hanoi ][vttest][      ]"
QACT1:  DB "Queens N=00                     "
QACT2:  DB "Recursive all-solutions         "
QACT3:  DB "View boards or count            "
QACT4:  DB "[view  ][count ][new n ][menu  ]"
HACT1:  DB "Hanoi N=00                      "
HACT2:  DB "Three pegs A -> C using B       "
HACT3:  DB "Recursive minimal move stream   "
HACT4:  DB "[start ][new n ][      ][menu  ]"
QSR1:   DB "Queens search N=00              "
QSR2:   DB "Found=0000                      "
QSR3:   DB "Work=|                          "
QSR4:   DB "[      ][      ][      ][menu  ]"
NN1:    DB "New N                           "
NN2:    DB "Type decimal 1..10, then EXE    "
NN3:    DB "                                "
NN4:    DB "[      ][      ][      ][menu  ]"
NN_BADROW:DB "Invalid N - use 1..10           "
BLANK32:DB "                                "

; NUL-terminated VT strings, all intentionally fit columns 3..30.
VQ_TITLE:DB "N-Queens N=",0
VQ_SOL:  DB "Sol=",0
VQ_NEXT: DB "Q next  MENU top  BRK exit",0
VQ_DONE: DB "N-Queens complete",0
VQ_NLAB: DB "N=",0
VQ_TOT:  DB "Total=",0
VQ_BACK: DB "Q back  MENU top  BRK exit",0
VH_TITLE:DB "Hanoi N=",0
VH_MOVES:DB "Moves ",0
VH_DASH: DB "-",0
VH_NEXT: DB "Q next  MENU top  BRK exit",0
VH_FINAL:DB "Q done  MENU top  BRK exit",0
VH_DONE: DB "Hanoi complete",0
VH_TOTAL:DB "Total moves=",0
VTT_SUFFIX:DB " lorem ipsum dolor sit",0

; ======================================================================
; INHERITED BOOT ROM KEY TRANSLATION TABLE - byte-identical mapping.
; Relocated to 7000; INKEY refers to the symbolic KEYSCAN address.
; ======================================================================
        ORG     &H7000
KEYSCAN:
KSCAN01:DB      0,0,0,0,0,0,0,1,0,0,0,0
KSCAN02:DB      "W","Q","A",0,"Z",0,0,0,0,0,"'",7
KSCAN03:DB      "R","E","D","S","C","X",0,0,&HFC,0,&H29,&H28
KSCAN04:DB      "Y","T","G","F","B","V",0,0,&HFD,0,&H5D,&H5B
KSCAN05:DB      "I","U","J","H","M","N",0,0,&HFE,0,&H90,&H7C
KSCAN06:DB      "P","O","L","K",&H20,",",0,0,&HFF,0,&H93,&H94
KSCAN07:DB      0,"=",":",";",0,0,0,0,&H95,0,0,&H9B
KSCAN08:DB      "5","4","2","1",0,"0",0,"7",0,0,0,0
KSCAN09:DB      "-","6","+","3",&H0D,".",0,"9",0,0,0,0
KSCAN10:DB      &H9D,&H1C,"/",&H08,0,0,0,"*",0,0,&H9C,&H11
KSCAN11:DB      &H1F,&H1D,&H0C,0,0,0,0,"8",0,0,&H1E,&H12

        ORG     &HFFFF
        DB      0