@8bitscript/cx16 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8BitScript contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,153 @@
+{
+  "name": "@8bitscript/cx16",
+  "version": "0.1.0",
+  "description": "Commander X16 target support for 8BitScript: the hardware underneath the portable APIs.",
+  "license": "MIT",
+  "8bitscript": {
+    "entry": "./src/index.8bs",
+    "exports": {
+      "./screen": "./src/screen.8bs",
+      "./text": "./src/text.8bs",
+      "./banks": "./src/banks.8bs",
+      "./mouse": "./src/mouse.8bs",
+      "./input": "./src/input.8bs",
+      "./pointer": "./src/pointer.8bs"
+    },
+    "hardware": {
+      "facts": {
+        "video.columns": 76,
+        "video.rows": 56,
+        "video.cellWidth": 8,
+        "video.cellHeight": 8,
+        "video.palette": 256,
+        "video.cellColors": 2,
+        "video.colorPerCell": true,
+        "video.glyphs": 256,
+        "video.blockWidth": 2,
+        "video.blockHeight": 2,
+        "video.bitmap": true,
+        "video.layers": 2,
+        "video.scroll": true,
+        "video.sprites": 128,
+        "video.spritesPerLine": 46,
+        "video.spriteWidth": 64,
+        "video.spriteHeight": 64,
+        "video.spriteColors": 255,
+        "video.frameRate": 60,
+        "audio.voices": 25,
+        "audio.noise": true,
+        "audio.envelope": true,
+        "audio.filter": false,
+        "audio.pcm": true,
+        "audio.volume": true,
+        "audio.entropy": false,
+        "input.keyboard": true,
+        "input.joysticks": 0,
+        "input.pads": 2,
+        "input.mouse": true,
+        "input.paddles": false,
+        "storage.save": true,
+        "memory.ram": 38655,
+        "memory.banked": true,
+        "memory.bankedKib": 512,
+        "storage.kib": 32768
+      },
+      "run": {
+        "x16emu": [
+          "-capture"
+        ]
+      },
+      "options": {
+        "ram": {
+          "label": "Banked RAM",
+          "default": "512",
+          "detect": "@8bitscript/cx16/banks",
+          "values": {
+            "64": {
+              "label": "64 KiB of banked RAM",
+              "run": {
+                "x16emu": [
+                  "-ram",
+                  "64"
+                ]
+              },
+              "facts": {
+                "memory.bankedKib": 64
+              }
+            },
+            "128": {
+              "label": "128 KiB of banked RAM",
+              "run": {
+                "x16emu": [
+                  "-ram",
+                  "128"
+                ]
+              },
+              "facts": {
+                "memory.bankedKib": 128
+              }
+            },
+            "256": {
+              "label": "256 KiB of banked RAM",
+              "run": {
+                "x16emu": [
+                  "-ram",
+                  "256"
+                ]
+              },
+              "facts": {
+                "memory.bankedKib": 256
+              }
+            },
+            "512": {
+              "label": "512 KiB of banked RAM",
+              "run": {
+                "x16emu": [
+                  "-ram",
+                  "512"
+                ]
+              },
+              "facts": {
+                "memory.bankedKib": 512
+              }
+            },
+            "1024": {
+              "label": "1024 KiB of banked RAM",
+              "run": {
+                "x16emu": [
+                  "-ram",
+                  "1024"
+                ]
+              },
+              "facts": {
+                "memory.bankedKib": 1024
+              }
+            },
+            "2048": {
+              "label": "2048 KiB of banked RAM",
+              "run": {
+                "x16emu": [
+                  "-ram",
+                  "2048"
+                ]
+              },
+              "facts": {
+                "memory.bankedKib": 2048
+              }
+            }
+          }
+        }
+      },
+      "presets": {}
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/banks.8bs

@@ -0,0 +1,128 @@
+// @8bitscript/cx16/banks — how much banked RAM this X16 has.
+//
+// Named by "8bitscript".exports["./banks"] in this package's package.json:
+//
+//     import { banks } from "@8bitscript/cx16/banks";
+//
+//     let kib: usmallint = banks.kib();   // 64 .. 2048
+//
+// A run-time hardware probe, like @8bitscript/c64/reu. The X16's banked
+// RAM is not a fixed amount: a board carries anywhere from 64 KiB to 2
+// MiB of it, `x16emu -ram <KiB>` emulates each, and one binary runs on
+// all of them. The build says which the *emulator* is fitted with (the
+// catalog's `ram` option; `Memory.BANKED_KIB` from @8bitscript/system),
+// and this says what the machine the program is running on really has. A
+// program that never imports this file carries none of it.
+//
+// Banked RAM is 8 KiB pages seen through the window at `$A000`–`$BFFF`,
+// the page selected by a write to `$0000` (the X16 puts its two bank
+// registers in the zero page, which is why the SDK's own zero-page
+// allocation starts at `$0022`). A machine has a power of two of them, 8
+// pages (64 KiB) to 256 (2 MiB). So the count is found by asking about
+// pages 8, 16, 32, 64 and 128 in turn: the first one the machine does not
+// really have is the count.
+//
+// "Does not really have" has two shapes, and the probe tests for both,
+// because which one a machine shows is the machine's business:
+//
+// 1. **It is a page it does have, under another number.** A board that
+//    keeps fewer than 8 bits of the page register wraps, so page N is
+//    page (N mod count). Every page tested here is one above a power of
+//    two, so where it wraps it lands on page 1 — the page the KERNAL
+//    leaves to us — and the test is whether page N+1 shows a marker just
+//    written to page 1. It is confirmed with a second, different marker,
+//    so a page that merely happens to hold those two bytes is not
+//    mistaken for a mirror.
+// 2. **It is nothing at all.** Then the window floats: writes do not
+//    stick and reads return whatever was last on the bus. Verified under
+//    x16emu, which is this shape — with `-ram 64`, a byte written to
+//    page 200 read back as `$A0`, the high byte of the window's own
+//    address, and page 9 read `$3E`. So the second test is the plain
+//    one: write two different bytes and read both back.
+//
+// Only pages 1 and N+1 are ever written, and page N+1 only after it has
+// been shown not to be a mirror — page 0 is the KERNAL's own workspace
+// and is never touched. The two bytes at `$A000`–`$A001` of page 1 are
+// scribbled on, so call this at start-up, before storing anything in
+// banked RAM, and keep the answer. Page 1 is left selected, which is
+// where the KERNAL leaves it.
+//
+// (The KERNAL can answer this too — `MEMTOP` with carry set returns the
+// page count — but calling it means a JSR with register conventions the
+// language has no spelling for. See ../AGENTS.md.)
+
+namespace Bank {
+    const SELECT: usmallint = 0x0000;    // the RAM page register
+    const WINDOW: usmallint = 0xA000;    // first byte of the 8 KiB window
+    const WINDOW1: usmallint = 0xA001;   // and the second
+    const OURS: utinyint = 1;            // the page the KERNAL leaves to us
+}
+
+export namespace banks {
+    // Put `value` and its complement in our own page's first two bytes.
+    function mark(value: utinyint): void {
+        memory.write(Bank.SELECT, Bank.OURS);
+        memory.write(Bank.WINDOW, value);
+        memory.write(Bank.WINDOW1, value ^ 0xFF);
+    }
+
+    // Does `page` show what mark(value) wrote — is it our own page under
+    // another number?
+    function shows(page: utinyint, value: utinyint): bool {
+        memory.write(Bank.SELECT, page);
+        if (memory.read(Bank.WINDOW) != value) {
+            return false;
+        }
+        return memory.read(Bank.WINDOW1) == (value ^ 0xFF);
+    }
+
+    // Is `page` real memory? Two different bytes, both read back: a
+    // floating window echoes at most one of them.
+    function backed(page: utinyint): bool {
+        memory.write(Bank.SELECT, page);
+        memory.write(Bank.WINDOW, 0x5A);
+        memory.write(Bank.WINDOW1, 0xA5);
+        if (memory.read(Bank.WINDOW) != 0x5A) {
+            return false;
+        }
+        return memory.read(Bank.WINDOW1) == 0xA5;
+    }
+
+    // The 8 KiB pages of banked RAM this machine has: 8, 16, 32, 64, 128
+    // or 256.
+    function count(): usmallint {
+        let pages: utinyint = 8;
+        while (pages != 0) {
+            let above: utinyint = pages + Bank.OURS;
+            banks.mark(0x5A);
+            if (banks.shows(above, 0x5A)) {
+                banks.mark(0xC3);
+                if (banks.shows(above, 0xC3)) {
+                    return banks.answer(pages);   // a mirror of our own page
+                }
+            }
+            if (!banks.backed(above)) {
+                return banks.answer(pages);       // nothing there
+            }
+            pages = pages * 2;
+        }
+        return banks.answer(0);
+    }
+
+    // Leave page 1 selected, as the KERNAL does, and widen the count; 0
+    // pages means the register never ran out, which is all 256.
+    function answer(pages: utinyint): usmallint {
+        memory.write(Bank.SELECT, Bank.OURS);
+        if (pages == 0) {
+            return 256;
+        }
+        let found: usmallint = pages;
+        return found;
+    }
+
+    // KiB of banked RAM plugged in: 64 on the smallest board, 2048 on the
+    // largest. One call at start-up; keep the answer.
+    function kib(): usmallint {
+        return banks.count() * 8;
+    }
+}

package/src/index.8bs

@@ -0,0 +1,111 @@
+// @8bitscript/cx16 — Commander X16 target support: the hardware underneath.
+//
+// See ../AGENTS.md before extending this package: the X16 has a great deal
+// of hardware, all of it behind windows, ports, and firmware, and the rules
+// there are about keeping bank state, VERA state, and optional hardware out
+// of game code.
+//
+// The module entry point named by the "8bitscript".entry field in this
+// package's package.json, resolved and linked for:
+//
+//     import { setVramAddress, locateTextMap, mapBank, mapLow } from "@8bitscript/cx16";
+//
+// What a program usually wants sits one layer up, in this package's own
+// implementations of the portable capability packages — `./src/screen.8bs`
+// behind @8bitscript/screen and `./src/text.8bs` behind @8bitscript/text,
+// named by the "8bitscript".exports map in package.json — which are built
+// on what this file exports and on nothing else. Where a Commodore
+// package's hardware surface is a set of registers, the X16's is a PORT:
+// VERA's video memory is not CPU-addressable, so what this file exports is
+// the address-port sequence every VRAM access performs, and where the text
+// map currently is.
+//
+// ---- what the program finds when main() runs ---------------------------
+//
+// LLVM-MOS's cx16 start-up code prints CHR$(15) through the KERNAL's CHROUT
+// immediately before calling main() — verified by disassembling a linked
+// build (`lda #$0f / jsr $ffd2 / jsr main`, in the SDK's start-up
+// sequence after `_start`; llvm-objdump labels the block with a local
+// symbol, `shift`). CHR$(15) switches the X16 KERNAL's screen editor into
+// ISO mode so that C's ASCII strings print as ASCII, and the KERNAL clears
+// the screen as part of that switch. Two consequences every program on this
+// target inherits, and the screen and text modules are written around:
+//
+//   1. The screen is blank when main() starts — the boot banner is gone —
+//      and it is the KERNAL's default blue (palette index 6) because that
+//      is the background nibble the KERNAL cleared every cell with. A
+//      program that sets a border and nothing else therefore appears to do
+//      nothing: examples/borders looked like exactly that, a solid blue
+//      screen, before screen.8bs painted anything itself.
+//
+//   2. The screen is in ISO mode: the character set VERA is drawing from
+//      is the KERNAL's ISO-8859-15 set, whose tile index IS the character
+//      code — 'A' is 65, '0' is 48, space is 32 — not the PETSCII screen
+//      codes (A = 1) the Commodore machines' screen memory takes.
+//      `text.putChar` takes ASCII on every machine, so here it passes the
+//      code straight through, where the Commodore packages translate.
+//
+// ---- VRAM through VERA's port ---------------------------------------------
+//
+// The text layer (layer 1 in the KERNAL's boot configuration: 1bpp
+// 16-colour text, a tile map 128 tiles wide by 64 high, of which 80x60 are
+// on screen at boot and 76x56 inside this package's border inset —
+// screen_init in the ROM's kernal/drivers/x16/screen.s) takes
+// each cell's colours from that cell's own attribute byte — high nibble
+// background, low nibble foreground — stored in VRAM, which the CPU reaches
+// only through VERA's address/data port: write the 17-bit address into
+// $9F20 (bits 7:0), $9F21 (15:8) and $9F22 (bit 16, plus the auto-increment
+// step in bits 7:4), then read or write $9F23 (DATA0), which advances the
+// address by that step. Cell (x, y) is char byte base + y*256 + x*2,
+// attribute byte one higher.
+//
+// Where `base` is comes from VERA, not from this file: the KERNAL puts
+// the map at $1B000 today, but that is a constant in its source
+// (inc/io.inc), not a published contract, and the ROM's own documentation
+// reserves the right to move it. VERA's layer registers read back what
+// was written to them (verified in the emulator's video_read), so
+// locateTextMap() below reads L1_MAPBASE ($9F35) — the map address
+// divided by 512 — before every access and derives the 17-bit base from
+// it. What this file still assumes is the shape screen_init gives the
+// map: 128 tiles wide (a 256-byte row stride), and wholly within one
+// 64 KiB half of VRAM so the low 16 bits of any cell fit a usmallint.
+//
+// Interrupts are on while main() runs (the frame driver only disables
+// them afterwards), and the KERNAL's IRQ handler drives the mouse-cursor
+// sprite and the cursor blink through this same port. That is safe: both
+// wrap their work in the ROM's screen_save_state/screen_restore_state,
+// which save VERA CTRL, FX_CTRL and ADDR0 (kernal/drivers/x16/screen.s),
+// so an interrupt landing between the three address writes and the data
+// write finds everything as it left it.
+//
+// Writing CTRL ($9F25) also clears ADDRSEL (bit 0), selecting DATA0 — the
+// port everything here uses; screen.8bs sets CTRL itself both times it
+// needs the other DCSEL view, and leaves it 0 (the KERNAL's default).
+
+// The text map's VRAM address, as (bit 16, low 16 bits), refreshed from
+// VERA by locateTextMap() — see above for why it is read, not known. Two
+// globals rather than a return value because a function returns one
+// value, and this is two.
+export let mapBank: utinyint = 0;
+export let mapLow: usmallint = 0;
+
+// L1_MAPBASE ($9F35) holds the map address >> 9: bit 7 is VRAM bit 16,
+// bits 6:0 are address bits 15:9.
+export function locateTextMap(): void {
+    mapBank = memory.read(0x9F35) / 128;
+    // Two steps, not `(byte % 128) * 512`: the product can reach 65024,
+    // past a 16-bit signed int, and in the C this becomes that is
+    // undefined arithmetic on a promoted byte (LLVM-MOS happens to wrap;
+    // nothing promises it). Multiplying a usmallint keeps it unsigned.
+    mapLow = memory.read(0x9F35) % 128;
+    mapLow = mapLow * 512;
+}
+
+// Point DATA0 at a 17-bit VRAM address (bank = bit 16, low = bits 15:0),
+// with the auto-increment step index in the top nibble of $9F22 (0 = no
+// step, 1 = +1, 2 = +2 — VERA's table of steps, not a byte count).
+export function setVramAddress(bank: utinyint, low: usmallint, stepIndex: utinyint): void {
+    memory.write(0x9F20, low % 256);
+    memory.write(0x9F21, low / 256);
+    memory.write(0x9F22, bank + stepIndex * 16);
+}

package/src/input.8bs

@@ -0,0 +1,146 @@
+// @8bitscript/cx16/input — the Commander X16 behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.cx16 in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file on an X16.
+//
+// ---- what this layer answers ----------------------------------------------
+//
+// **The pointer, through the KERNAL.** `$FF68` mouse_config, `$FF71`
+// mouse_scan and `$FF6B` mouse_get, wrapped by ./mouse.8bs. A menu asks
+// "did the user just press", so the button is edge-triggered: true on the
+// one frame the press begins, false while it is held. `poll()` has to be
+// called exactly once a frame — twice a frame and every press is seen once
+// and then swallowed. See ./mouse.8bs for why mouse_scan is called from
+// here rather than left to the KERNAL IRQ (the frame driver has interrupts
+// off).
+//
+// **Nothing else yet.** The keyboard is PS/2 decoded into a KERNAL queue
+// (`$FFE4` GETIN) and the SNES-style pads are another KERNAL call
+// (`$FF56` joystick_get). Both are still unreachable from this file for
+// the same reason the mouse was: they need `asm6502` blocks and care about
+// what the KERNAL expects to still be true when they are called. They are
+// the next thing this layer should grow, not a gap this file hides —
+// `left()`/`right()`/`confirm()`/`cancel()` stay false, and a program
+// still links.
+//
+// **`input.mouse` is true on this machine by default**, because the
+// hardware really does have one. `HAS_MOUSE` is that fact, so on a future
+// build that could take the mouse out the pointer half of this file is
+// `if (false)` and LLVM deletes it. Today there is no such catalog option;
+// the emulator's mouse is always there.
+//
+// **The pointer is reported in cells, not pixels.** `pointerCell()` is a
+// flat cell index, the same number `text.print()` takes. The KERNAL's
+// position is a pixel from the top-left of the *active area* — the same
+// origin cell (0, 0) has after screen.8bs insets the display so VERA's
+// border colour has somewhere to show. An earlier draft subtracted that
+// 16-pixel inset again, and the arrow sat two cells down-right of the
+// cell `pointerCell()` named: mouse_get said (319, 239) and the sprite
+// was on screen at (335, 254), which is (319, 239) plus the inset, so
+// the KERNAL is already in the inset space. Shift down by the 8-pixel
+// cell size; a pointer past the visible 76×56 clamps to the last cell.
+import { mouse } from "./mouse.8bs";
+
+const HAS_MOUSE: bool = #fact(input.mouse);
+
+const COLUMNS: usmallint = #fact(video.columns);
+const ROWS: usmallint = #fact(video.rows);
+const CELL_SHIFT: utinyint = 3; // 8 pixels a cell
+
+namespace Edge {
+    const LEFT: utinyint = 1;
+    const RIGHT: utinyint = 2;
+    const UP: utinyint = 4;
+    const DOWN: utinyint = 8;
+    const CONFIRM: utinyint = 16;
+    const CANCEL: utinyint = 32;
+    const BUTTON: utinyint = 64;
+}
+
+let held: utinyint = 0;
+let before: utinyint = 0;
+let began: utinyint = 0;
+
+let atCell: usmallint = 0;
+
+// Pixel to a column or row on the visible grid: shift down by the cell
+// size, clamp to the last cell. mouse_get's origin is the active area's
+// top-left (see the header), so there is no inset to subtract.
+function cellOn(pixel: usmallint, limit: usmallint): usmallint {
+    let at: usmallint = pixel >> CELL_SHIFT;
+    if (at >= limit) {
+        return limit - 1;
+    }
+    return at;
+}
+
+export namespace input {
+
+    function begin(): void {
+        if (HAS_MOUSE) {
+            mouse.begin();
+        }
+    }
+
+    // Once a frame, right after waitFrame(), and never twice.
+    function poll(): void {
+        if (HAS_MOUSE) {
+            mouse.poll();
+        }
+
+        before = held;
+        held = 0;
+
+        if (HAS_MOUSE) {
+            let column: usmallint = cellOn(mouse.x(), COLUMNS);
+            let row: usmallint = cellOn(mouse.y(), ROWS);
+            atCell = row * COLUMNS + column;
+            if (mouse.left()) {
+                held = held | Edge.BUTTON;
+            }
+        }
+
+        began = held & (before ^ 0xFF);
+    }
+
+    function left(): bool {
+        return (began & Edge.LEFT) != 0;
+    }
+
+    function right(): bool {
+        return (began & Edge.RIGHT) != 0;
+    }
+
+    function up(): bool {
+        return (began & Edge.UP) != 0;
+    }
+
+    function down(): bool {
+        return (began & Edge.DOWN) != 0;
+    }
+
+    function confirm(): bool {
+        return (began & Edge.CONFIRM) != 0;
+    }
+
+    function cancel(): bool {
+        return (began & Edge.CANCEL) != 0;
+    }
+
+    function pointer(): bool {
+        return HAS_MOUSE;
+    }
+
+    function pointerCell(): usmallint {
+        return atCell;
+    }
+
+    function pointerButton(): bool {
+        return (began & Edge.BUTTON) != 0;
+    }
+}

package/src/mouse.8bs

@@ -0,0 +1,187 @@
+// @8bitscript/cx16/mouse — the X16's PS/2 mouse, through the KERNAL.
+//
+// Named by "8bitscript".exports["./mouse"] in this package's package.json:
+//
+//     import { mouse } from "@8bitscript/cx16/mouse";
+//
+//     mouse.begin();                   // once, at start-up
+//     ...
+//     waitFrame();
+//     mouse.poll();                    // once a frame
+//     if (mouse.present()) { ... mouse.x() ... }
+//
+// The X16 has no control-port mouse and no registers a program pokes. The
+// pointer is a KERNAL service: `$FF68` mouse_config turns it on (and the
+// firmware draws it as VERA sprite 0), `$FF71` mouse_scan reads the PS/2
+// device and moves that sprite, `$FF6B` mouse_get copies the position and
+// buttons out. All three were read in the ROM this package was verified
+// against — x16-rom `fbe32a60`, `kernal/drivers/x16/ps2mouse.s` — not
+// recalled.
+//
+// **Why poll() calls ps2data_fetch then mouse_scan.** The frame driver
+// disables interrupts (FRAME_SYNC.cx16's `sei`, every waitFrame(), so it
+// can own VERA's VSYNC bit instead of racing the KERNAL IRQ for it). The
+// KERNAL IRQ is what would have called extapi `$08` ps2data_fetch (poll
+// the SMC) and then mouse_scan. mouse_scan only applies bytes already in
+// that buffer — with the IRQ silenced, a scan alone is a no-op and the
+// sprite stays at mouse_config's rest position. `$FEAB` with A=8 is the
+// published fetch; it is not re-entrant, which is why poll() `sei`s first.
+// mouse_scan then saves and restores VERA address state around the sprite
+// write (the same screen_save_state/restore_state the IRQ uses), so a
+// program's text port is still where it left it.
+//
+// **Why the buffer lives at `$80`–`$84`.** mouse_get wants a zero-page
+// address in X and writes four consecutive bytes there (X lo/hi, Y lo/hi),
+// returning buttons in A. The SDK's cx16 link script gives the *program*
+// `$02`–`$7F` (`__basic_zp_end = $80`), and LLVM-MOS allocates that range
+// for imaginary registers and `.zp.noinit` variables. An earlier draft
+// parked this buffer at `$7B` and `sta $7B` for the buttons overwrote
+// `there` every poll — `present()` was false on a machine whose pointer
+// was drawing in the middle of the screen. `$80`–`$84` is the first byte
+// the program is not given, so the linker will not put a variable there.
+// The KERNAL's mouse state lives in banked KVARSB0, not here.
+//
+// **Presence is the fact, not a probe.** A 1351 says it is there through
+// the SID's pots; the X16's KERNAL does not. `input.mouse` is true on the
+// stock sheet because the hardware has a mouse (the emulator's is always
+// there), and `present()` is that fact. A stored flag set before a KERNAL
+// call and read after it is not safe: `asm6502` is opaque, LLVM may keep
+// the flag in a register the call trashes — measured, with the pointer
+// drawing at (319, 239) while `present()` was false. A board whose SMC
+// reports `BAT_FAIL` ($FC) leaves the mouse off and this file will still
+// say present. That case has not been seen under x16emu; *to verify* on a
+// machine with the mouse unplugged.
+//
+// **The rest position is the centre**, not the corner. mouse_config with
+// a nonzero size (this file asks screen_mode, $FF5F, carry set, for the
+// current 8-pixel size — 80×60 in the KERNAL's text mode) parks the
+// pointer at half that range. Under x16emu that is pixel (319, 239) of
+// the 640×480 output. Movement is not exercised headlessly: nothing in a
+// `--screenshot` run moves the host pointer x16emu reads.
+const HAS_MOUSE: bool = #fact(input.mouse);
+
+// mouse_get's 4-byte position (X, then Y, 16-bit little-endian each) and
+// the button byte it returns in A. See the header for why these addresses.
+@address(0x80)
+let posX: volatile<usmallint>;
+@address(0x82)
+let posY: volatile<usmallint>;
+@address(0x84)
+let rawButtons: volatile<utinyint>;
+
+// Copied out of the buffer during poll(), so every caller in a frame
+// shares one reading — the same discipline @8bitscript/c64/mouse holds
+// to, even though these locations do not run on their own the way the
+// SID's converter does.
+let atX: usmallint = 0;
+let atY: usmallint = 0;
+let heldButtons: utinyint = 0;
+let started: bool = false;
+
+export namespace Mouse {
+    const LEFT: utinyint = 1;
+}
+
+export namespace mouse {
+
+    // Once, at start-up, before the first poll(). Turns the KERNAL mouse
+    // on at the current screen's 8-pixel size, which also loads the default
+    // pointer into sprite 0 and parks it at the centre. Harmless to call
+    // twice: the second call is skipped, so input.begin() and pointer.begin()
+    // can both name it without re-centering.
+    function begin(): void {
+        if (HAS_MOUSE) {
+            if (started) {
+                return;
+            }
+            started = true;
+            asm6502 {
+                sec
+                jsr $FF5F
+                lda #1
+                jsr $FF68
+                ldx #$80
+                jsr $FF6B
+                sta $84
+            }
+            atX = posX;
+            atY = posY;
+            heldButtons = rawButtons;
+        }
+    }
+
+    // Once a frame, after waitFrame(). Fetch from the SMC first (the IRQ
+    // is off), then mouse_scan, then mouse_get into the buffer, then copy.
+    // One reading, kept.
+    function poll(): void {
+        if (HAS_MOUSE) {
+            asm6502 {
+                sei
+                lda #8
+                jsr $FEAB
+                jsr $FF71
+                ldx #$80
+                jsr $FF6B
+                sta $84
+            }
+            atX = posX;
+            atY = posY;
+            heldButtons = rawButtons;
+        }
+    }
+
+    // True on a build fitted with a mouse, which is every stock X16. This
+    // is the fact, not a stored flag: an `asm6502` block is opaque to
+    // LLVM, so a bool set before a KERNAL call and read after it can be
+    // kept in a register the call trashes. Measured: `there = true` in
+    // begin() then mouse_get in poll() left present() false while the
+    // pointer was drawing at (319, 239).
+    function present(): bool {
+        return HAS_MOUSE;
+    }
+
+    // Pixel position from the top-left of the active area — the same
+    // origin cell (0, 0) has after screen.8bs insets the display. The
+    // KERNAL parks a freshly configured mouse at half the current
+    // screen_mode range; under x16emu that is (319, 239), which is the
+    // centre of the 640×480 the mode names, not of the inset picture.
+    function x(): usmallint {
+        return atX;
+    }
+
+    function y(): usmallint {
+        return atY;
+    }
+
+    // The left button, as of the last poll(). Bit 0 of mouse_get's A,
+    // which ps2mouse.s documents as left (bit 1 right, bit 2 middle).
+    function left(): bool {
+        return (heldButtons & Mouse.LEFT) != 0;
+    }
+
+    // Hide the pointer and stop tracking. pointer.hide() is the caller;
+    // the next show() turns tracking back on without re-centering
+    // (mouse_config $FF, size left as-is).
+    function hide(): void {
+        if (HAS_MOUSE) {
+            asm6502 {
+                lda #0
+                ldx #0
+                ldy #0
+                jsr $FF68
+            }
+        }
+    }
+
+    // Undo hide(): mouse on, keep the current cursor and position.
+    function show(): void {
+        if (HAS_MOUSE) {
+            asm6502 {
+                lda #$FF
+                ldx #0
+                ldy #0
+                jsr $FF68
+            }
+        }
+    }
+}

package/src/pointer.8bs

@@ -0,0 +1,77 @@
+// @8bitscript/cx16/pointer — the X16 behind @8bitscript/pointer: the
+// KERNAL's own mouse cursor.
+//
+// Named by "8bitscript".exports["./pointer"] in this package's package.json,
+// and by "8bitscript".entry.cx16 in @8bitscript/pointer's, so a portable
+// program writes
+//
+//     import { pointer } from "@8bitscript/pointer";
+//
+// and gets this file on an X16. It is the *visible* half of the pointer
+// @8bitscript/input already reports: `input` says where the pointer is and
+// whether its button went down, and this says what the user sees while
+// they aim it.
+//
+// ---- the firmware draws it ------------------------------------------------
+//
+// This is the one machine of the nine where a program need not draw a
+// cursor at all. `$FF68` mouse_config (./mouse.8bs's begin()) loads the
+// KERNAL's default pointer — Susan Kare's 16×16 1bpp arrow — into VERA
+// sprite 0 and the firmware moves it. `update()` here is therefore empty
+// on the happy path: `input.poll()` has already called mouse_scan, which
+// writes the sprite's position. A program that never polls gets an arrow
+// that never moves, the same contract as on the C64.
+//
+// `DRAWS` is `#fact(input.mouse)`, true on the stock machine. The rest
+// position is the *centre* of the 640×480 output, not the corner: that is
+// where mouse_config parks it, verified in ps2mouse.s (x16-rom fbe32a60).
+//
+// `setColor` does nothing. The firmware pointer is 1bpp black and white,
+// not a VIC-style sprite colour this layer can poke without fighting the
+// KERNAL's sprite_set_image. Studio asks for white, which is already what
+// the arrow's fill is.
+//
+// `hide()` turns the KERNAL mouse off (mouse_config 0) and `update()`
+// turns it back on without re-centering (mouse_config $FF, size left
+// as-is), so a program that hides for one frame — the pointer example's
+// cancel — gets the arrow back on the next without a jump.
+import { mouse } from "./mouse.8bs";
+
+const HAS_MOUSE: bool = #fact(input.mouse);
+
+let hidden: bool = false;
+
+export namespace pointer {
+
+    const DRAWS: bool = #fact(input.mouse);
+
+    function begin(): void {
+        if (HAS_MOUSE) {
+            // input.begin() has usually already done this; mouse.begin()
+            // is skipped the second time so the pointer is not re-centered.
+            mouse.begin();
+        }
+    }
+
+    function setColor(color: utinyint): void {
+        if (HAS_MOUSE) {
+            // The firmware pointer is black and white; see the header.
+        }
+    }
+
+    function update(): void {
+        if (HAS_MOUSE) {
+            if (hidden) {
+                mouse.show();
+                hidden = false;
+            }
+        }
+    }
+
+    function hide(): void {
+        if (HAS_MOUSE) {
+            mouse.hide();
+            hidden = true;
+        }
+    }
+}

package/src/screen.8bs

@@ -0,0 +1,230 @@
+// @8bitscript/cx16/screen — the Commander X16's implementation of
+// @8bitscript/screen.
+//
+// Named by "8bitscript".exports["./screen"] in this package's package.json,
+// and what
+//
+//     import { screen, BorderColor, BackgroundColor } from "@8bitscript/screen";
+//
+// resolves to when the build is for the X16: @8bitscript/screen's entry is
+// keyed by machine and delegates here. Built on the VERA port protocol
+// @8bitscript/cx16 exports — read that file first for what the KERNAL
+// leaves on screen and how VRAM is reached. Every machine's screen.8bs
+// exports this same surface, which is what lets a program import it from
+// @8bitscript/screen and never name the hardware.
+import { mapBank, mapLow, locateTextMap, setVramAddress } from "./index.8bs";
+
+// ---- where a border comes from --------------------------------------------
+//
+// VERA's border colour is a plain CPU-addressable register — but the
+// border it colours has no size by default. VERA draws layers inside an
+// "active area" whose edges are DC_HSTART/HSTOP/VSTART/VSTOP, and the
+// KERNAL boots with that area set to the entire 640x480 output, so nothing
+// is left over for the border colour to fill. Setting the border alone is
+// invisible — the second reason examples/borders once showed only blue.
+//
+// So setColors() shrinks the active area by 16 pixels on every side —
+// HSTART/HSTOP count in units of 4 pixels (0..160), VSTART/VSTOP in units
+// of 2 (0..240), hence 4/156 and 8/232 — and VERA fills the 16-pixel ring
+// outside it with the border colour. The text layer is positioned relative
+// to the active area, so cell (0,0) sits at the inset's top-left corner
+// and the map's rightmost 4 columns and bottom 4 rows fall outside the
+// active area: the grid a program sees is the 76x56 that is drawn
+// (text.COLUMNS / text.CELL_COUNT say so), not the map's 80x60. This
+// is the closest thing the X16 has to the VIC/VIC-II's dedicated border
+// area, and like the NES's drawn frame it is honest about what it is: a
+// choice this module makes, not a register the machine has.
+//
+// "Relative" needs one correction, measured rather than assumed. Under
+// x16emu r50 the layer's first line lands TWO lines above the active
+// area's top edge whenever VSTART is nonzero: with a 16-line inset, row 0
+// of text occupied lines 14-21 and its top two lines were hidden under
+// the border, and the same two lines with a 32-line inset. The emulator's
+// video.c shows why — its layer line counter starts accumulating on the
+// VSTART line through a two-line register-history pipeline (the one that
+// models VERA's own raster-effect latency), so the active area's first
+// line already reads as layer line 2. setColors() compensates with layer
+// 1's vertical scroll: 510, which is -2 modulo the map's 512 lines, puts
+// layer line 0 on the active area's first line exactly (verified the same
+// way: row 0's glyphs occupy lines 16-23 with the 16-line inset, none
+// hidden). The horizontal edge needs no such correction. Real hardware
+// has not been checked; if VERA silicon has no such offset, the visible
+// symptom would be the map's last row showing in the top two lines — so
+// the repaint below covers that row too and keeps its characters blank.
+//
+// The four DC_ registers live at $9F29-$9F2C under two views selected by
+// DCSEL (CTRL $9F25 bit 1): DCSEL=0 is VIDEO/HSCALE/VSCALE/BORDER, DCSEL=1
+// is HSTART/HSTOP/VSTART/VSTOP — confirmed against llvm-mos-sdk's cx16.h,
+// which lays out `struct __vera` exactly so. setColors() sets DCSEL
+// itself both times and leaves it 0 (the KERNAL's default), so nothing
+// here assumes what a previous program left it at.
+//
+// ---- the background: painted, not set ---------------------------------------
+//
+// There is no screen-background register at all: each text cell's colours
+// come from its own attribute byte in VRAM (see @8bitscript/cx16). So the
+// background is painted: setColors() writes every one of the 4800
+// on-screen cells' attribute bytes to `background` in the high nibble and
+// white (1) in the low — 60 rows of 80 auto-incrementing writes — the same
+// way the Commodore packages draw their digits in white against whatever
+// background is chosen. Around 60,000 cycles at 8MHz, a few milliseconds:
+// VERA's VRAM is safe to write at any point in the frame (a write mid-frame
+// can tear for that one frame; it cannot corrupt anything, unlike the
+// NES's port), so this needs no vblank budget and setColors() is safe from
+// the frame loop as well as from setup. Its side effect is deliberate and
+// documented: any foreground colour a program set with text.putColor() is
+// reset to white by the next setColors().
+//
+// Colours are VERA palette indices. The KERNAL's default palette starts
+// with the sixteen C64 colours in C64 order — 0 black, 1 white, 2 red,
+// 3 cyan, 4 purple, 5 green, 6 blue, 7 yellow, and so on — verified on
+// screen under x16emu for the values examples/borders uses, so the
+// Commodore packages' colour numbers mean the same colours here.
+
+// The border exists once the active area is inset — 16 pixels in on
+// every side — and layer 1 is scrolled so cell (0,0) lands at its corner.
+// Done by whichever screen call comes first, once.
+let insetDone: utinyint = 0;
+
+function insetPicture(): void {
+    if (insetDone == 1) {
+        return;
+    }
+    insetDone = 1;
+    // DCSEL=1: the active-area edges.
+    memory.write(0x9F25, 0x02);
+    memory.write(0x9F29, 4);    // HSTART: 16px
+    memory.write(0x9F2A, 156);  // HSTOP: 624px
+    memory.write(0x9F2B, 8);    // VSTART: 16px
+    memory.write(0x9F2C, 232);  // VSTOP: 464px
+    memory.write(0x9F25, 0x00); // back to DCSEL=0
+    // Layer 1's scroll: horizontal 0, vertical 510 = -2 mod the map's
+    // 512 lines — the two-line correction the header explains, so that
+    // cell (0,0) lands exactly at the active area's top-left corner.
+    memory.write(0x9F37, 0x00); // L1_HSCROLL_L
+    memory.write(0x9F38, 0x00); // L1_HSCROLL_H
+    memory.write(0x9F39, 0xFE); // L1_VSCROLL_L: 510 & 0xFF
+    memory.write(0x9F3A, 0x01); // L1_VSCROLL_H: 510 >> 8
+}
+
+export namespace screen {
+    function setColors(border: u8, background: u8): void {
+        insetPicture();
+        // DCSEL=0 (and ADDRSEL=0): the border colour itself.
+        memory.write(0x9F25, 0x00);
+        memory.write(0x9F2C, border);
+
+        // Every cell's attribute byte: background high, white low. All 64
+        // map rows, not just the 60 on screen — row 63 is what the
+        // vertical-scroll correction above would expose if real hardware
+        // lacks the offset it corrects (see the header), so it gets the
+        // same colours and, below, blank characters.
+        locateTextMap();
+        for (let row: usmallint = 0; row < 64; row++) {
+            setVramAddress(mapBank, mapLow + 1 + row * 256, 2);
+            for (let col: utinyint = 0; col < 80; col++) {
+                memory.write(0x9F23, background * 16 + 1);
+            }
+        }
+        setVramAddress(mapBank, mapLow + 63 * 256, 2);
+        for (let col: utinyint = 0; col < 80; col++) {
+            memory.write(0x9F23, 32);
+        }
+    }
+
+    // `blank(border, background)`: every cell blank and both colours set —
+    // black when left off, or `BorderColor.KEEP` / `BackgroundColor.KEEP`
+    // to leave one as it is. `setBorder` and `setBackground` are one
+    // colour each, `setColors` the pair; `text.setColor` owns what the
+    // next print looks like.
+    function blank(border: utinyint = BorderColor.BLACK, background: utinyint = BackgroundColor.BLACK): void {
+        if (border != BorderColor.KEEP) {
+            screen.setBorder(border);
+        }
+        if (background != BackgroundColor.KEEP) {
+            screen.setBackground(background);
+        }
+        // Every character of all 64 map rows (see setColors above for why
+        // 64) blank; the attribute bytes between them are left alone.
+        locateTextMap();
+        for (let row: usmallint = 0; row < 64; row++) {
+            setVramAddress(mapBank, mapLow + row * 256, 2);
+            for (let col: utinyint = 0; col < 80; col++) {
+                memory.write(0x9F23, 32);
+            }
+        }
+    }
+
+    function setBackground(background: u8): void {
+        insetPicture();
+        // The background lives in every cell's attribute byte, so this is
+        // the same repaint setColors() does: background high, white low.
+        locateTextMap();
+        for (let row: usmallint = 0; row < 64; row++) {
+            setVramAddress(mapBank, mapLow + 1 + row * 256, 2);
+            for (let col: utinyint = 0; col < 80; col++) {
+                memory.write(0x9F23, background * 16 + 1);
+            }
+        }
+    }
+
+    function setBorder(border: u8): void {
+        insetPicture();
+        memory.write(0x9F25, 0x00); // DCSEL=0: the border colour register
+        memory.write(0x9F2C, border);
+    }
+}
+
+// ---- colour names ----------------------------------------------------------
+//
+// The same eight names every machine's screen.8bs exports — Black, White,
+// Red, Cyan, Purple, Green, Blue, Yellow — so a program can write
+// `screen.setColors(BorderColor.BLUE, BackgroundColor.BLACK)` through
+// @8bitscript/screen and get blue on every target. The values are the first
+// sixteen entries of VERA's default palette, which are the C64's sixteen
+// colours in the C64's numbering (see above), so both namespaces carry all
+// sixteen.
+
+export namespace BorderColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}
+
+export namespace BackgroundColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}

package/src/text.8bs

@@ -0,0 +1,173 @@
+// @8bitscript/cx16/text — the Commander X16's implementation of
+// @8bitscript/text.
+//
+// Named by "8bitscript".exports["./text"] in this package's package.json,
+// and what
+//
+//     import { text } from "@8bitscript/text";
+//
+// resolves to when the build is for the X16. Built on the VERA port protocol
+// @8bitscript/cx16 exports — read that file first for what the KERNAL
+// leaves on screen and how VRAM is reached. Every machine's text.8bs
+// exports this same namespace — the same names, the same shapes, ASCII
+// codes, and a cell 0 at the top-left corner inside the border — so a
+// program that imports it from @8bitscript/text draws the same thing on
+// every target.
+import { mapBank, mapLow, locateTextMap, setVramAddress } from "./index.8bs";
+
+// 76x56 = 4256 cells, row-major (the map is 80x60; screen.8bs's border
+// inset shows 76x56 of it, and that is the grid); codes are ASCII, as on every machine, and
+// here that is also what the hardware wants (ISO mode — see
+// @8bitscript/cx16). Each cell is two bytes in the map — the character,
+// then its attribute byte: background colour in the high nibble,
+// foreground in the low.
+//
+// putColor is real here, unlike on the NES and Atari: it sets a cell's
+// foreground nibble and leaves the background nibble as it finds it — a
+// read-modify-write through the same port, with the auto-increment step at
+// 0 so the read and the write land on one byte (VERA fetches the byte when
+// the address is set, so DATA0 reads it back without moving). Whose
+// background that nibble holds is not this module's business: the KERNAL's
+// blue before screen.setColors() has painted, the painted colour after.
+
+// ---- print: strings and number fields ------------------------------------
+//
+// `text.print(cell, s)` writes a string's characters into consecutive
+// cells from `cell`, and `text.printNumber(cell, value, width)` writes
+// `value` as exactly `width` decimal digits, zero-padded and right-aligned,
+// so a field on a HUD never shifts columns. Both draw in the current colour —
+// white until `text.setColor(TextColor.CYAN)` changes it, and that one
+// call then colours everything printed after it, on the machines that have
+// per-cell colour. They are also the two
+// functions the compiler's template layout targets: `text.print(0,
+// \`TICK ${ticks:1}\`)` is laid out at compile time into these same calls
+// (see packages/compiler/src/ir).
+//
+// Under them: `locate()` turns a cell into a
+// VERA address without dividing, and a run of text lets VERA step the
+// address itself.
+// `text.putChar` and `text.putColor` stay the one-cell pokes a caller can
+// build anything from.
+let currentColor: utinyint = 1; // white, until text.setColor() says otherwise
+let currentReverse: bool = false; // until text.setReverse() says otherwise
+
+// ISO mode has no reverse copies of the glyphs, so invert is a swap of
+// the attribute nibbles: the cell fills with the text colour and the
+// glyph pixels take whatever background `screen.setColors` left. Port 1
+// is already sitting on this cell's colour byte after locate().
+function attributeByte(): utinyint {
+    let attr: utinyint = memory.read(0x9F24);
+    if (currentReverse) {
+        return (currentColor * 16) + (attr / 16);
+    }
+    return (attr & 0xF0) | currentColor;
+}
+
+// Point VERA at a cell, and hand back its column for a caller that walks
+// on from there. Rows are 256 bytes apart in the map, cells two bytes —
+// character, then colour (background in the high nibble, text in the low).
+// No division: with 76 cells to a row and 256 = 3 * 76 + 28, a cell's row
+// is three per 256 plus (28 * high byte + low byte) / 76, and that last
+// quotient, on a number below 704, is ((x / 4) * 54) / 1024 exactly —
+// checked for every cell. Two address ports: port 0 walks character, colour,
+// character... stepping by one, and is what gets written; port 1 walks the
+// colour bytes stepping by two, and is read for each cell's background
+// nibble so a print keeps whatever `screen.setBackground` put there.
+// Leaves ADDRSEL at 0, which screen.8bs assumes.
+function locate(cell: usmallint): utinyint {
+    locateTextMap();
+    let high: utinyint = cell / 256;
+    let x: usmallint = high * 28 + cell % 256;
+    let row: utinyint = high * 3 + ((x / 4) * 54) / 1024;
+    let col: utinyint = cell - row * 76;
+    let at: usmallint = mapLow + row * 256 + col * 2;
+    memory.write(0x9F25, 0x01); // ADDRSEL=1
+    setVramAddress(mapBank, at + 1, 2);
+    memory.write(0x9F25, 0x00); // ADDRSEL=0
+    setVramAddress(mapBank, at, 1);
+    return col;
+}
+
+// ---- digits -------------------------------------------------------------
+//
+// A number is written one place at a time, high to low, by subtracting the
+// place value until it no longer fits: the 6502 has no divide instruction,
+// and `value / 10` would link a 250-byte routine to do it. Places above the
+// field are still taken off, so a field narrower than its number shows the
+// low digits; places the number does not reach print as zeros.
+const DIGIT_PLACES: array<usmallint, 5> = [10000, 1000, 100, 10, 1];
+
+export namespace text {
+    const CELL_COUNT: usmallint = 4256; // 76 columns x 56 rows, inside the inset
+    const COLUMNS: utinyint = 76; // cells per row, so cell = y * text.COLUMNS + x
+
+    function putChar(cell: usmallint, code: utinyint): void {
+        locate(cell);
+        memory.write(0x9F23, code);
+    }
+
+    function putColor(cell: usmallint, color: utinyint): void {
+        locate(cell);
+        memory.read(0x9F23); // step port 0 past the character byte
+        memory.write(0x9F23, (memory.read(0x9F24) & 0xF0) | (color & 0x0F));
+    }
+
+    function setColor(color: utinyint): void {
+        currentColor = color;
+    }
+
+    function setReverse(on: bool): void {
+        currentReverse = on;
+    }
+
+    function print(cell: usmallint, s: string): void {
+        let col: utinyint = locate(cell);
+        for (let i: utinyint = 0; i < s.length; i++) {
+            memory.write(0x9F23, s[i]);
+            memory.write(0x9F23, attributeByte());
+            col++;
+            if (col == text.COLUMNS) {
+                col = locate(cell + i + 1); // the next row is not the next address
+            }
+        }
+    }
+
+    function printNumber(cell: usmallint, value: usmallint, width: utinyint): void {
+        let col: utinyint = locate(cell);
+        let k: utinyint = width;
+        if (k < DIGIT_PLACES.length) {
+            k = DIGIT_PLACES.length;
+        }
+        while (k > 0) {
+            let digit: utinyint = 48; // '0'
+            if (k <= DIGIT_PLACES.length) {
+                while (value >= DIGIT_PLACES[DIGIT_PLACES.length - k]) {
+                    value = value - DIGIT_PLACES[DIGIT_PLACES.length - k];
+                    digit++;
+                }
+            }
+            if (k <= width) {
+                memory.write(0x9F23, digit);
+                memory.write(0x9F23, attributeByte());
+                col++;
+                if (col == text.COLUMNS) {
+                    col = locate(cell + width - k + 1); // the next row is not the next address
+                }
+            }
+            k--;
+        }
+    }
+}
+
+// The colours `text.setColor()` takes: the eight names every machine
+// shares, with this machine's colour-RAM values.
+export namespace TextColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+}