@8bitscript/nes 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/native/6502/font.s

@@ -0,0 +1,212 @@
+; @8bitscript/nes — the CHR-ROM character set.
+;
+; The NES has no character ROM of its own. Every Commodore machine and the
+; Atari 8-bit ship their letters and digits in a ROM the video chip reads
+; directly, so `text.putChar` on those targets only ever writes a code
+; into screen memory. The NES PPU reads its 8x8 tile patterns from the
+; CARTRIDGE (CHR-ROM on NROM), so a cartridge that shows text has to bring
+; its own — this file is that ROM, linked into the .nes image through this
+; package's "8bitscript".native list (see package.json and docs/packages.md).
+;
+; Layout: pattern table 0 ($0000-$0FFF), 256 tiles of 16 bytes, laid out so
+; that TILE INDEX == ASCII CODE for every glyph here — space ($20), the
+; digits ($30-$39), A-Z ($41-$5A), and ! , - . : ? — so @8bitscript/nes's
+; `text.putChar(cell, code)` writes the ASCII code straight into the
+; nametable with no translation table, the same codes examples/borders'
+; Atari variant already uses. Codes in $20-$5F with no glyph drawn render
+; blank. Tile $80 is solid colour index 2 — the tile @8bitscript/nes lays
+; around the screen edge as the drawn "border" (see index.8bs). Reverse
+; video of $20-$5F lives at ASCII+128 ($A0-$DF), leaving $80 alone.
+; Everything else, including all of pattern table 1 ($1000-$1FFF), is blank.
+;
+; Tile format (nesdev.org/wiki/PPU_pattern_tables): 8 bytes of bitplane 0
+; then 8 bytes of bitplane 1, one byte per row, bit 7 the leftmost pixel.
+; A pixel's colour index is plane1:plane0, so a glyph with rows in plane 0
+; and zeros in plane 1 is drawn entirely in colour index 1 — palette entry
+; $3F01, the text colour screen.setColors() sets — and the solid tile, with zeros
+; in plane 0 and $FF in plane 1, is entirely colour index 2 ($3F02).
+; The binary literals below therefore ARE the glyph artwork: read each
+; `tile` line's eight rows top to bottom, 1 = lit.
+
+.section .chr_rom,"a"
+
+.macro tile r0, r1, r2, r3, r4, r5, r6, r7
+    .byte \r0, \r1, \r2, \r3, \r4, \r5, \r6, \r7
+    .byte 0, 0, 0, 0, 0, 0, 0, 0
+.endm
+
+; Reverse of a glyph: plane 0 inverted, plane 1 still clear, so lit pixels
+; become the backdrop and the rest of the cell takes colour index 1 — the
+; text colour. A reverse space is therefore a solid block in that colour.
+.macro itile r0, r1, r2, r3, r4, r5, r6, r7
+    .byte 0xff^\r0, 0xff^\r1, 0xff^\r2, 0xff^\r3, 0xff^\r4, 0xff^\r5, 0xff^\r6, 0xff^\r7
+    .byte 0, 0, 0, 0, 0, 0, 0, 0
+.endm
+
+.macro rfill
+    .byte 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF
+    .byte 0, 0, 0, 0, 0, 0, 0, 0
+.endm
+
+; $00-$20: control codes and space — 33 blank tiles.
+.space 33 * 16
+
+; $21 '!'
+tile 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00000000, 0b00000000, 0b00011000, 0b00000000
+
+; $22-$2B: " # $ % & ' ( ) * + — 10 blank tiles.
+.space 10 * 16
+
+; $2C ','
+tile 0b00000000, 0b00000000, 0b00000000, 0b00000000, 0b00011000, 0b00011000, 0b00110000, 0b00000000
+; $2D '-'
+tile 0b00000000, 0b00000000, 0b00000000, 0b01111110, 0b00000000, 0b00000000, 0b00000000, 0b00000000
+; $2E '.'
+tile 0b00000000, 0b00000000, 0b00000000, 0b00000000, 0b00000000, 0b00011000, 0b00011000, 0b00000000
+
+; $2F '/' — blank.
+.space 16
+
+; $30-$39 '0'-'9'
+tile 0b00111100, 0b01100110, 0b01101110, 0b01110110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+tile 0b00011000, 0b00111000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b01111110, 0b00000000
+tile 0b00111100, 0b01100110, 0b00000110, 0b00001100, 0b00110000, 0b01100000, 0b01111110, 0b00000000
+tile 0b00111100, 0b01100110, 0b00000110, 0b00011100, 0b00000110, 0b01100110, 0b00111100, 0b00000000
+tile 0b00001100, 0b00011100, 0b00111100, 0b01101100, 0b01111110, 0b00001100, 0b00001100, 0b00000000
+tile 0b01111110, 0b01100000, 0b01111100, 0b00000110, 0b00000110, 0b01100110, 0b00111100, 0b00000000
+tile 0b00111100, 0b01100000, 0b01111100, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+tile 0b01111110, 0b00000110, 0b00001100, 0b00011000, 0b00110000, 0b00110000, 0b00110000, 0b00000000
+tile 0b00111100, 0b01100110, 0b01100110, 0b00111100, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+tile 0b00111100, 0b01100110, 0b01100110, 0b00111110, 0b00000110, 0b00001100, 0b00111000, 0b00000000
+
+; $3A ':'
+tile 0b00000000, 0b00011000, 0b00011000, 0b00000000, 0b00011000, 0b00011000, 0b00000000, 0b00000000
+
+; $3B-$3E: ; < = > — 4 blank tiles.
+.space 4 * 16
+
+; $3F '?'
+tile 0b00111100, 0b01100110, 0b00000110, 0b00001100, 0b00011000, 0b00000000, 0b00011000, 0b00000000
+
+; $40 '@' — blank.
+.space 16
+
+; $41-$5A 'A'-'Z'
+tile 0b00011000, 0b00111100, 0b01100110, 0b01111110, 0b01100110, 0b01100110, 0b01100110, 0b00000000
+tile 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b00000000
+tile 0b00111100, 0b01100110, 0b01100000, 0b01100000, 0b01100000, 0b01100110, 0b00111100, 0b00000000
+tile 0b01111000, 0b01101100, 0b01100110, 0b01100110, 0b01100110, 0b01101100, 0b01111000, 0b00000000
+tile 0b01111110, 0b01100000, 0b01100000, 0b01111000, 0b01100000, 0b01100000, 0b01111110, 0b00000000
+tile 0b01111110, 0b01100000, 0b01100000, 0b01111000, 0b01100000, 0b01100000, 0b01100000, 0b00000000
+tile 0b00111100, 0b01100110, 0b01100000, 0b01101110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+tile 0b01100110, 0b01100110, 0b01100110, 0b01111110, 0b01100110, 0b01100110, 0b01100110, 0b00000000
+tile 0b00111100, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00111100, 0b00000000
+tile 0b00011110, 0b00001100, 0b00001100, 0b00001100, 0b00001100, 0b01101100, 0b00111000, 0b00000000
+tile 0b01100110, 0b01101100, 0b01111000, 0b01110000, 0b01111000, 0b01101100, 0b01100110, 0b00000000
+tile 0b01100000, 0b01100000, 0b01100000, 0b01100000, 0b01100000, 0b01100000, 0b01111110, 0b00000000
+tile 0b01100011, 0b01110111, 0b01111111, 0b01101011, 0b01100011, 0b01100011, 0b01100011, 0b00000000
+tile 0b01100110, 0b01110110, 0b01111110, 0b01111110, 0b01101110, 0b01100110, 0b01100110, 0b00000000
+tile 0b00111100, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+tile 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b01100000, 0b01100000, 0b01100000, 0b00000000
+tile 0b00111100, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00001110, 0b00000000
+tile 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b01111000, 0b01101100, 0b01100110, 0b00000000
+tile 0b00111100, 0b01100110, 0b01100000, 0b00111100, 0b00000110, 0b01100110, 0b00111100, 0b00000000
+tile 0b01111110, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00000000
+tile 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+tile 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00011000, 0b00000000
+tile 0b01100011, 0b01100011, 0b01100011, 0b01101011, 0b01111111, 0b01110111, 0b01100011, 0b00000000
+tile 0b01100110, 0b01100110, 0b00111100, 0b00011000, 0b00111100, 0b01100110, 0b01100110, 0b00000000
+tile 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00011000, 0b00011000, 0b00011000, 0b00000000
+tile 0b01111110, 0b00000110, 0b00001100, 0b00011000, 0b00110000, 0b01100000, 0b01111110, 0b00000000
+
+; $5B-$7F: [ \ ] ^ _ ` a-z { | } ~ DEL — 37 blank tiles (no lowercase yet).
+.space 37 * 16
+
+; $80: the solid tile — every pixel colour index 2 (plane 1 set, plane 0
+; clear), so it takes whatever palette entry $3F02 holds: `border`.
+.byte 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
+.byte 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF
+
+; $81-$9F: 31 blank tiles — a gap so reverse copies can sit at ASCII+128
+; without colliding with the border tile at $80.
+.space 31 * 16
+
+; $A0-$DF: reverse video of $20-$5F. Tile index == ASCII + 128, the same
+; rule Commodore screen codes use, so `text.setReverse` is `code + 128`.
+; Inverted blanks (and the reverse space at $A0) are solid colour index 1.
+; $A0 reverse space
+rfill
+; $A1 reverse '!'
+itile 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00000000, 0b00000000, 0b00011000, 0b00000000
+; $A2-$AB: reverse of the $22-$2B blanks
+.rept 10
+    rfill
+.endr
+; $AC reverse ','
+itile 0b00000000, 0b00000000, 0b00000000, 0b00000000, 0b00011000, 0b00011000, 0b00110000, 0b00000000
+; $AD reverse '-'
+itile 0b00000000, 0b00000000, 0b00000000, 0b01111110, 0b00000000, 0b00000000, 0b00000000, 0b00000000
+; $AE reverse '.'
+itile 0b00000000, 0b00000000, 0b00000000, 0b00000000, 0b00000000, 0b00011000, 0b00011000, 0b00000000
+; $AF reverse of blank '/'
+rfill
+; $B0-$B9 reverse '0'-'9'
+itile 0b00111100, 0b01100110, 0b01101110, 0b01110110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+itile 0b00011000, 0b00111000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b01111110, 0b00000000
+itile 0b00111100, 0b01100110, 0b00000110, 0b00001100, 0b00110000, 0b01100000, 0b01111110, 0b00000000
+itile 0b00111100, 0b01100110, 0b00000110, 0b00011100, 0b00000110, 0b01100110, 0b00111100, 0b00000000
+itile 0b00001100, 0b00011100, 0b00111100, 0b01101100, 0b01111110, 0b00001100, 0b00001100, 0b00000000
+itile 0b01111110, 0b01100000, 0b01111100, 0b00000110, 0b00000110, 0b01100110, 0b00111100, 0b00000000
+itile 0b00111100, 0b01100000, 0b01111100, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+itile 0b01111110, 0b00000110, 0b00001100, 0b00011000, 0b00110000, 0b00110000, 0b00110000, 0b00000000
+itile 0b00111100, 0b01100110, 0b01100110, 0b00111100, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+itile 0b00111100, 0b01100110, 0b01100110, 0b00111110, 0b00000110, 0b00001100, 0b00111000, 0b00000000
+; $BA reverse ':'
+itile 0b00000000, 0b00011000, 0b00011000, 0b00000000, 0b00011000, 0b00011000, 0b00000000, 0b00000000
+; $BB-$BE: reverse of the $3B-$3E blanks
+.rept 4
+    rfill
+.endr
+; $BF reverse '?'
+itile 0b00111100, 0b01100110, 0b00000110, 0b00001100, 0b00011000, 0b00000000, 0b00011000, 0b00000000
+; $C0 reverse of blank '@'
+rfill
+; $C1-$DA reverse 'A'-'Z'
+itile 0b00011000, 0b00111100, 0b01100110, 0b01111110, 0b01100110, 0b01100110, 0b01100110, 0b00000000
+itile 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b00000000
+itile 0b00111100, 0b01100110, 0b01100000, 0b01100000, 0b01100000, 0b01100110, 0b00111100, 0b00000000
+itile 0b01111000, 0b01101100, 0b01100110, 0b01100110, 0b01100110, 0b01101100, 0b01111000, 0b00000000
+itile 0b01111110, 0b01100000, 0b01100000, 0b01111000, 0b01100000, 0b01100000, 0b01111110, 0b00000000
+itile 0b01111110, 0b01100000, 0b01100000, 0b01111000, 0b01100000, 0b01100000, 0b01100000, 0b00000000
+itile 0b00111100, 0b01100110, 0b01100000, 0b01101110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+itile 0b01100110, 0b01100110, 0b01100110, 0b01111110, 0b01100110, 0b01100110, 0b01100110, 0b00000000
+itile 0b00111100, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00111100, 0b00000000
+itile 0b00011110, 0b00001100, 0b00001100, 0b00001100, 0b00001100, 0b01101100, 0b00111000, 0b00000000
+itile 0b01100110, 0b01101100, 0b01111000, 0b01110000, 0b01111000, 0b01101100, 0b01100110, 0b00000000
+itile 0b01100000, 0b01100000, 0b01100000, 0b01100000, 0b01100000, 0b01100000, 0b01111110, 0b00000000
+itile 0b01100011, 0b01110111, 0b01111111, 0b01101011, 0b01100011, 0b01100011, 0b01100011, 0b00000000
+itile 0b01100110, 0b01110110, 0b01111110, 0b01111110, 0b01101110, 0b01100110, 0b01100110, 0b00000000
+itile 0b00111100, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+itile 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b01100000, 0b01100000, 0b01100000, 0b00000000
+itile 0b00111100, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00001110, 0b00000000
+itile 0b01111100, 0b01100110, 0b01100110, 0b01111100, 0b01111000, 0b01101100, 0b01100110, 0b00000000
+itile 0b00111100, 0b01100110, 0b01100000, 0b00111100, 0b00000110, 0b01100110, 0b00111100, 0b00000000
+itile 0b01111110, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00011000, 0b00000000
+itile 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00000000
+itile 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00011000, 0b00000000
+itile 0b01100011, 0b01100011, 0b01100011, 0b01101011, 0b01111111, 0b01110111, 0b01100011, 0b00000000
+itile 0b01100110, 0b01100110, 0b00111100, 0b00011000, 0b00111100, 0b01100110, 0b01100110, 0b00000000
+itile 0b01100110, 0b01100110, 0b01100110, 0b00111100, 0b00011000, 0b00011000, 0b00011000, 0b00000000
+itile 0b01111110, 0b00000110, 0b00001100, 0b00011000, 0b00110000, 0b01100000, 0b01111110, 0b00000000
+; $DB-$DF: reverse of the $5B-$5F blanks
+.rept 5
+    rfill
+.endr
+
+; $E0-$FF: 32 blank tiles, completing pattern table 0 at exactly 4096 bytes.
+.space 32 * 16
+
+; Pattern table 1 ($1000-$1FFF): unused, blank. Spelled out rather than left
+; to the linker's padding so the section is exactly the 8 KiB the iNES
+; header declares for NROM, whatever the linker script does with a short one.
+.space 4096

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@8bitscript/nes",
+  "version": "0.1.0",
+  "description": "NES 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",
+      "./pad": "./src/pad.8bs",
+      "./input": "./src/input.8bs",
+      "./pointer": "./src/pointer.8bs"
+    },
+    "native": [
+      "./native/6502/font.s"
+    ],
+    "hardware": {
+      "facts": {
+        "video.columns": 28,
+        "video.rows": 26,
+        "video.cellWidth": 8,
+        "video.cellHeight": 8,
+        "video.palette": 25,
+        "video.cellColors": 3,
+        "video.colorPerCell": false,
+        "video.glyphs": 0,
+        "video.blockWidth": 0,
+        "video.blockHeight": 0,
+        "video.bitmap": false,
+        "video.layers": 1,
+        "video.scroll": true,
+        "video.sprites": 64,
+        "video.spritesPerLine": 8,
+        "video.spriteWidth": 8,
+        "video.spriteHeight": 16,
+        "video.spriteColors": 3,
+        "video.frameRate": 60,
+        "audio.voices": 5,
+        "audio.noise": true,
+        "audio.envelope": true,
+        "audio.filter": false,
+        "audio.pcm": true,
+        "audio.volume": true,
+        "audio.entropy": false,
+        "input.keyboard": false,
+        "input.joysticks": 0,
+        "input.pads": 2,
+        "input.mouse": false,
+        "input.paddles": false,
+        "storage.save": false,
+        "memory.ram": 1536,
+        "memory.banked": false,
+        "memory.bankedKib": 0,
+        "storage.kib": 0
+      },
+      "options": {
+        "mapper": {
+          "label": "Cartridge board",
+          "default": "nrom",
+          "values": {
+            "nrom": {
+              "label": "NROM: 32K PRG, 8K CHR-ROM, no save",
+              "build": {
+                "driver": "mos-nes-nrom-clang",
+                "output": "nes"
+              },
+              "facts": {
+                "storage.save": false
+              }
+            }
+          }
+        }
+      },
+      "presets": {}
+    }
+  },
+  "files": [
+    "src",
+    "native"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.8bs

@@ -0,0 +1,185 @@
+// @8bitscript/nes — NES target support: the hardware underneath.
+//
+// See ../AGENTS.md before extending this package: the NES PPU is tile/pattern
+// oriented rather than a framebuffer, its 64-sprite budget is really an
+// 8-per-scanline budget, and its mapper (only NROM is wired up today) is a
+// build profile question, not a language one — mistakes easy to bake into
+// comments or APIs here if copied from a generic "8-bit" mental model.
+//
+// The module entry point named by the "8bitscript".entry field in this
+// package's package.json, resolved and linked for:
+//
+//     import { setVramAddress, resetScroll } from "@8bitscript/nes";
+//
+// 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 NES's is a
+// PROTOCOL: the PPU's memory is not CPU-addressable at all, so the two
+// functions here are the port sequence every VRAM access on this machine
+// has to perform, and the two rules that come with it.
+//
+// ---- VRAM through the PPU's port -----------------------------------------
+//
+// Screen memory is not a fixed CPU address: the nametable lives in the
+// PPU's own 16 KiB address space, reached only through an indirect port —
+// read PPUSTATUS ($2002) to reset the shared address/scroll write toggle,
+// write PPUADDR ($2006) twice (high byte, then low) to latch a VRAM address,
+// then write PPUDATA ($2007), which stores through it and auto-increments.
+// Two rules that protocol brings, both of which the screen and text
+// modules honour so callers need not:
+//
+//   1. Writing PPUADDR moves the PPU's internal address register, which is
+//      also what it scrolls from when rendering resumes — leave it pointing
+//      into the middle of the nametable and the next frame draws from
+//      there. Every text.putChar() and screen.setColors() ends by resetting
+//      the scroll (PPUCTRL $2000 = 0, then PPUSCROLL $2005 = 0 twice), so
+//      the picture stays anchored at the top-left. Invisible while every
+//      tile was blank; not once there is something on screen to shift.
+//
+//   2. While rendering is ON, the PPU owns VRAM outside vertical blank,
+//      and a write outside it lands wherever the PPU's address happens to
+//      be — a corrupted tile and a torn frame. Vertical blank is about
+//      2270 CPU cycles, and a program cannot be asked to know that. So
+//      the text and palette writes do not go to the PPU when a program
+//      makes them: they go into the queue below, as runs of bytes at a
+//      VRAM address, and `nesVerticalBlank()` delivers the whole queue
+//      at the start of the next vertical blank — packages/backend-6502's
+//      frame runtime calls it right after every hardware frame edge
+//      (FRAME_SYNC.nes.frameHook), before waitFrame() returns. Delivery
+//      is a tight loop, about 15 cycles a byte — but that number alone
+//      is what let this queue overrun the blank in the first place: it
+//      prices the data bytes and forgets each run's own header (a
+//      setVramAddress() call plus its two-write PPUADDR protocol), which
+//      is not free. A HUD of a few wide rows is nearly all data bytes and
+//      pays that header cost once or twice; a grid of many narrow fields
+//      (2048's 4-character tile cells, three text.print() runs per tile)
+//      pays it on almost every run. QUEUE_SIZE was 128 — "about four
+//      28-column rows," sized against the wide-row case — until 2048's
+//      16-tile board (packages/2048, one run per tile row, ~19 runs to
+//      fill one queue) proved by measurement that a full 128-byte queue
+//      of small runs delivers a few cycles past the 2270-cycle blank,
+//      corrupting whichever tile was mid-flight when the PPU's own
+//      rendering resumed under it (FCEUX, `8bs run nes --screenshot`,
+//      2026-09-07: 128 corrupted two tiles, every size 120 and under
+//      across both a two-tile and a full sixteen-tile board did not, 124
+//      did). 112 is the fixed value now: comfortable under the observed
+//      failure band, not the exact edge of it, since neither this
+//      project's timing model nor FCEUX's is being trusted to a single
+//      cycle. A future program with even smaller, more numerous runs
+//      than 2048's could still find a new floor; measure again with
+//      `--screenshot` before assuming this one holds. more than a full
+//      queue in one frame is delivered as it overflows, which may tear.
+//      screen.blank() switches rendering off and writes the nametable
+//      directly, delivering the queue first so nothing printed before
+//      the blank appears after it.
+//
+// Nametable and attribute contents are undefined at power-on (real
+// hardware: garbage; FCEUX: zeros, which is why a program that forgot to
+// clear would look fine in the emulator and wrong on a cartridge) — a
+// program should clear the screen once before screen.setColors(), as
+// examples/borders does; the attribute table is cleared by screen.8bs,
+// since a program has no other way to reach it.
+//
+// PPU warm-up: NESdev's guidance is to wait for two vertical blanks after
+// reset before writing the PPU at all, since the chip is not stable for
+// roughly the first 29,658 CPU cycles. LLVM-MOS's NROM start-up code does
+// exactly that before main() — verified by disassembling mos-platform/
+// nes-nrom/lib/crt0.o: __early_init writes $2000/$2001/$4010 = 0, clears
+// $2002, and spins on it until bit 7 sets; __late_init spins on it once
+// more after RAM is initialised — so by the time a program's main() runs
+// the PPU has seen two vblanks and is safe to write. (An earlier revision
+// of this comment recorded that wait as a gap this target still had; it
+// was never one.)
+
+// PPUSTATUS read resets the PPUADDR/PPUSCROLL write toggle so the two
+// PPUADDR writes land as a fresh address rather than as a stray second
+// half of whatever came before.
+export function setVramAddress(address: usmallint): void {
+    memory.read(0x2002);
+    memory.write(0x2006, address / 256);
+    memory.write(0x2006, address % 256);
+}
+
+// PPUCTRL 0: nametable $2000, PPUDATA increments by 1, background patterns
+// from table 0 (where the font is), NMI off — this target polls PPUSTATUS
+// rather than taking the interrupt. Then PPUSCROLL x = 0, y = 0.
+export function resetScroll(): void {
+    memory.write(0x2000, 0x00);
+    memory.write(0x2005, 0x00);
+    memory.write(0x2005, 0x00);
+}
+
+// ---- the write queue -------------------------------------------------------
+//
+// Runs of bytes for the PPU, each a two-byte VRAM address (high, low), a
+// count, and the bytes: `queueRun(address)` opens one, `queueByte(value)`
+// adds to it, and `nesVerticalBlank()` writes them all out in order and
+// resets the scroll. Rule 2 above says why.
+const QUEUE_SIZE: utinyint = 112;
+let queue: array<utinyint, QUEUE_SIZE>;
+let queueEnd: utinyint = 0;
+let runCount: utinyint = 0; // where the open run's count byte is
+let runAddress: usmallint = 0; // the open run's VRAM address
+
+export function queueRun(address: usmallint): void {
+    if (queueEnd > QUEUE_SIZE - 4) {
+        deliverAtVerticalBlank(); // no room for a header and a byte
+    }
+    queue[queueEnd] = address / 256;
+    queue[queueEnd + 1] = address % 256;
+    runCount = queueEnd + 2;
+    queue[runCount] = 0;
+    queueEnd = queueEnd + 3;
+    runAddress = address;
+}
+
+export function queueByte(value: utinyint): void {
+    if (queueEnd == QUEUE_SIZE) {
+        // Full: deliver what there is and reopen the run where it left off.
+        queueRun(runAddress + queue[runCount]);
+    }
+    queue[queueEnd] = value;
+    queueEnd++;
+    queue[runCount]++;
+}
+
+// The queue is full before the frame is over: wait for the next vertical
+// blank and deliver it there. The program loses the rest of this frame —
+// a HUD too big for one frame costs frames, it never costs the picture.
+// Delivering mid-frame instead would corrupt it: PPUADDR is the PPU's
+// own fetch position while it draws, and PPUDATA writes move it. The
+// status read first clears a vertical-blank flag left over from earlier,
+// so the loop waits for the edge and not for a stale flag.
+function deliverAtVerticalBlank(): void {
+    memory.read(0x2002);
+    while (memory.read(0x2002) < 128) {
+    }
+    nesVerticalBlank();
+}
+
+// Every queued run to the PPU, then the scroll back to the top-left (each
+// run's PPUADDR write moved it). Called by the frame runtime at the start
+// of vertical blank; by deliverAtVerticalBlank() when the queue is full;
+// by screen.blank() with rendering off.
+export function nesVerticalBlank(): void {
+    let i: utinyint = 0;
+    while (i < queueEnd) {
+        setVramAddress(queue[i] * 256 + queue[i + 1]);
+        let n: utinyint = queue[i + 2];
+        i = i + 3;
+        // Indexed straight off `i`, one byte at a time: an `i + k` index
+        // made LLVM-MOS walk a pointer at 23 cycles a byte; this is 15.
+        while (n > 0) {
+            memory.write(0x2007, queue[i]);
+            i++;
+            n--;
+        }
+    }
+    if (queueEnd > 0) {
+        queueEnd = 0;
+        resetScroll();
+    }
+}

package/src/input.8bs

@@ -0,0 +1,141 @@
+// @8bitscript/nes/input — the NES behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.nes in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file on an NES. The pad itself is ./pad.8bs, which stays
+// available to a program that wants both controllers or the buttons this
+// file does not map.
+//
+// ---- what this machine has, and what it does not -------------------------
+//
+// This is the machine that makes the portable input surface worth having,
+// because it has none of what the others have. **No keyboard** — the fact
+// sheet says so (`input.keyboard` is false) and Studio reads that fact to
+// decide the NES is a viewer. **No pointer** — there is no mouse for a
+// stock NES, so `pointer()` is a constant false and everything that hangs
+// off it folds away. What there is, is a D-pad, and a D-pad is exactly
+// what a menu bar needs.
+//
+// So the mapping is the whole file:
+//
+//   - **left / right / up / down** — the D-pad on controller 1.
+//   - **confirm** — A, or START. START is included because on a console
+//     the button that opens a menu is the one people press to commit to
+//     something in it, and A is the one they press by reflex.
+//   - **cancel** — B.
+//
+// Controller 2 is read by ./pad.8bs and ignored here: the portable surface
+// describes one user driving one interface. A two-player program wants the
+// pad layer directly.
+//
+// ---- edges, not levels ---------------------------------------------------
+//
+// Every answer here is **edge-triggered**: true on the one frame the press
+// begins, false while it is held. Holding right does not race the highlight
+// across the bar. `poll()` must be called exactly once a frame, right after
+// waitFrame() — twice a frame and every press is seen once and swallowed.
+import { pad, Pad } from "./pad.8bs";
+
+// One bit per thing a program can ask about, so a frame's input is one
+// byte and an edge is one AND. The same seven bits as every other
+// machine's input layer; this one never sets BUTTON.
+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;
+}
+
+let held: utinyint = 0;
+let before: utinyint = 0;
+let began: utinyint = 0;
+
+export namespace input {
+
+    // Nothing to set up on this machine: the pad needs no configuration
+    // and there is no pointer to give a ceiling to. Here so that a program
+    // written for nine machines calls the same thing on all of them.
+    function begin(): void {
+    }
+
+    // Strobe the pad and work out what began this frame. Once a frame,
+    // right after waitFrame().
+    function poll(): void {
+        pad.scan();
+
+        before = held;
+        held = 0;
+
+        // The D-pad's four bits and the pad's own bit layout differ, so
+        // this is a translation rather than a mask — and it is four
+        // compares rather than a table because a table would cost a byte
+        // of RAM per entry to save nothing.
+        let buttons: utinyint = pad.bits(Pad.PORT_1);
+        if ((buttons & Pad.LEFT) != 0) {
+            held = held | Edge.LEFT;
+        }
+        if ((buttons & Pad.RIGHT) != 0) {
+            held = held | Edge.RIGHT;
+        }
+        if ((buttons & Pad.UP) != 0) {
+            held = held | Edge.UP;
+        }
+        if ((buttons & Pad.DOWN) != 0) {
+            held = held | Edge.DOWN;
+        }
+        if ((buttons & Pad.A) != 0 || (buttons & Pad.START) != 0) {
+            held = held | Edge.CONFIRM;
+        }
+        if ((buttons & Pad.B) != 0) {
+            held = held | Edge.CANCEL;
+        }
+
+        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;
+    }
+
+    // There is no pointer on an NES, and this is a constant — so a
+    // component's `if (input.pointer())` costs this machine nothing at
+    // all, which is the point of answering the question rather than
+    // leaving the call out.
+    function pointer(): bool {
+        return false;
+    }
+
+    function pointerCell(): usmallint {
+        return 0;
+    }
+
+    function pointerButton(): bool {
+        return false;
+    }
+}

package/src/pad.8bs

@@ -0,0 +1,120 @@
+// @8bitscript/nes/pad — the two controller ports, one snapshot a frame.
+//
+// Named by "8bitscript".exports["./pad"] in this package's package.json:
+//
+//     import { pad, Pad } from "@8bitscript/nes/pad";
+//
+//     pad.scan();
+//     if (pad.pressed(Pad.PORT_1, Pad.RIGHT)) { ... }
+//
+// Hardware-level, NES-only surface — the layer @8bitscript/nes/input sits
+// on, the way ./text.8bs sits under @8bitscript/text. Importing it makes a
+// program NES-specific. It keeps no history and decodes nothing; it
+// answers "is this button down now", which is what a frame loop asks.
+//
+// ---- how a controller talks ----------------------------------------------
+//
+// A standard controller is an 8-bit parallel-to-serial shift register, not
+// a set of addressable switches. Writing 1 then 0 to JOY1 ($4016) strobes
+// *both* ports: the 1 loads each pad's eight buttons into its register,
+// the 0 lets them be clocked out. After that, each read of $4016 returns
+// pad 1's next button in bit 0 and each read of $4017 returns pad 2's, in
+// this fixed order:
+//
+//     A, B, SELECT, START, UP, DOWN, LEFT, RIGHT
+//
+// A 1 bit is a button held down. Only bit 0 carries a button — the upper
+// bits are open bus on the NES and expansion-port data on a Famicom — so
+// every read is masked. Eight reads of two ports is about 200 cycles of a
+// 29780-cycle frame.
+//
+// `scan()` shifts each read into the top of a byte and shifts the byte
+// down, so after eight rounds the first button read (A) has travelled to
+// bit 0 and the last (RIGHT) sits at bit 7 — which is the `Pad.*` layout
+// below, and why there is no bit table here the way the C64's keyboard
+// needs one.
+//
+// ---- two things this file does not do, on purpose ------------------------
+//
+// **It does not re-read to defend against DMC corruption.** When the APU's
+// sample channel fetches a byte it can steal a cycle from a controller
+// read and drop or double-clock a bit — the reason commercial games read
+// the pad twice and keep the reading that agrees. Nothing in 8BitScript
+// drives the DMC channel today, so the defence would cost every program
+// cycles to guard against a channel no program can turn on. **When sample
+// playback arrives on this target, this is the file that has to grow the
+// double read**, and that is the note to find here when it does.
+//
+// **It does not know about a four-player adapter, a Zapper, or a Power
+// Pad.** Those change what the extra bits after the eighth read mean; this
+// reads eight and stops.
+//
+// Written from the documented strobe-then-eight-reads protocol (NESdev's
+// "Standard controller" and "Controller port registers"), which is the
+// sequence every NES program has used since 1983. **Not yet confirmed on
+// screen under a controller** — `--screenshot` builds and captures a
+// frame but cannot press a button, so the button order below is the
+// documented one and not a measured one. Anyone who runs
+// examples/first-look/menubar under FCEUX with a pad should replace this
+// paragraph with what they saw.
+
+// The two ports. JOY2's *write* side is the APU's frame counter, which is
+// why nothing here ever writes it — the strobe goes to JOY1 alone and
+// latches both pads.
+const JOY1: usmallint = 0x4016;
+const JOY2: usmallint = 0x4017;
+
+// The last scan: index 0 is port 1, index 1 is port 2; bits as in `Pad`.
+let state: array<utinyint, 2>;
+
+export namespace Pad {
+    const PORT_1: utinyint = 0;
+    const PORT_2: utinyint = 1;
+
+    // In the order the shift register clocks them out, which is the order
+    // the bits end up in after `scan()`.
+    const A: utinyint = 1;
+    const B: utinyint = 2;
+    const SELECT: utinyint = 4;
+    const START: utinyint = 8;
+    const UP: utinyint = 16;
+    const DOWN: utinyint = 32;
+    const LEFT: utinyint = 64;
+    const RIGHT: utinyint = 128;
+}
+
+export namespace pad {
+    // Strobe both pads and clock all sixteen buttons in. Once a frame,
+    // right after waitFrame().
+    function scan(): void {
+        memory.write(JOY1, 1);
+        memory.write(JOY1, 0);
+        // Both ports are clocked by the same eight reads, so they are read
+        // together rather than in two loops — one strobe, one pass.
+        let one: utinyint = 0;
+        let two: utinyint = 0;
+        for (let i: utinyint = 0; i < 8; i++) {
+            one = one >> 1;
+            if ((memory.read(JOY1) & 1) != 0) {
+                one = one | 128;
+            }
+            two = two >> 1;
+            if ((memory.read(JOY2) & 1) != 0) {
+                two = two | 128;
+            }
+        }
+        state[Pad.PORT_1] = one;
+        state[Pad.PORT_2] = two;
+    }
+
+    // The eight buttons of one port as `Pad.*` bits, 1 = held down.
+    function bits(port: utinyint): utinyint {
+        return state[port];
+    }
+
+    // Is this button — one `Pad.*` bit, or several or'd together — down in
+    // the last scan? Several bits ask "any of these".
+    function pressed(port: utinyint, button: utinyint): bool {
+        return (state[port] & button) != 0;
+    }
+}

package/src/pointer.8bs

@@ -0,0 +1,39 @@
+// @8bitscript/nes/pointer — the NES behind @8bitscript/pointer.
+//
+// Every call here does nothing and `DRAWS` is false. The PPU has 64
+// sprites and could draw an arrow without difficulty, so this is not the
+// drawing half that is missing — **it is that a stock NES has nothing to
+// move one with.** @8bitscript/nes/input reports a D-pad and buttons and
+// no pointer, because the console this repository builds for has two
+// controller ports and a cartridge, and a pad is not a pointer: a cursor
+// driven by a D-pad is a selection moving between items, which is what
+// `menubar.next()` and `previous()` already are, and dressing that up as
+// an arrow would be a worse interface, not a better one.
+//
+// The machine that *would* answer is a Zapper or a Power Pad, and neither
+// is a mouse either. A Famicom mouse existed and the hardware option for
+// one does not: packages/nes's catalog has no controller axis at all yet
+// (its mapper is still hard-wired — see packages/nes/AGENTS.md), so
+// fitting one would be a new option there first, then an input driver, and
+// only then this file.
+//
+// It costs the NES nothing: `DRAWS` is a const and every function is
+// empty, so a program's `if (pointer.DRAWS)` folds away and LLVM deletes
+// the calls — which matters most here, where a program has 2 KiB of RAM
+// and every byte of the cartridge is budgeted.
+export namespace pointer {
+
+    const DRAWS: bool = false;
+
+    function begin(): void {
+    }
+
+    function setColor(color: utinyint): void {
+    }
+
+    function update(): void {
+    }
+
+    function hide(): void {
+    }
+}

package/src/screen.8bs

@@ -0,0 +1,213 @@
+// @8bitscript/nes/screen — the NES'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 NES: @8bitscript/screen's entry is
+// keyed by machine and delegates here. Built on the PPU port protocol
+// @8bitscript/nes exports — read that file first for the two VRAM rules
+// this one lives by. 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 { setVramAddress, resetScroll, queueRun, queueByte, nesVerticalBlank } from "./index.8bs";
+
+// ---- what "border" means on a machine that has none --------------------
+//
+// The NES has no border-colour register. There is no separate border area
+// for one to colour: the PPU's 256x240 picture IS the whole frame, edge to
+// edge, and every one of those pixels comes from a background tile or a
+// sprite (or, where neither covers it, the universal backdrop colour). VIC,
+// VIC-II and GTIA all draw a picture smaller than the raster and paint the
+// margin around it from a dedicated register; the PPU simply has no
+// margin. So the border cannot be a register write here, the way it is on
+// every other target.
+//
+// It is real anyway. This module DRAWS a border: on the first setColors()
+// call it lays a two-tile-thick frame of a solid tile around the edge of
+// the nametable (rows 0-1 and 28-29, columns 0-1 and 30-31), and `border`
+// is the palette entry that solid tile takes its colour from. Two tiles
+// thick, not one, because NTSC televisions — and FCEUX, whose default NTSC
+// view drops the top and bottom 8 lines — overscan the outer tile row
+// away; the inner row survives. The text grid a program draws on (see
+// text.8bs) is the area INSIDE that frame: 28 columns by 26 rows, whose
+// cell 0 is nametable row 2, column 2 — the top-left corner, against the
+// border, which is exactly what cell 0 is on every other target. A program
+// never addresses the frame's own tiles, and never needs to know they
+// exist. The four values setColors() writes are, in the PPU's own terms:
+//
+//     $3F00  universal backdrop     `background`
+//     $3F01  colour index 1         $30 (white) — every glyph in the font
+//     $3F02  colour index 2         `border` — the solid frame tile
+//     $3F03  colour index 3         unused
+//
+// all in background palette 0, which every tile on screen uses (the
+// attribute table is zeroed by the same first call, so no 32x32-pixel block
+// picks another palette). Both colours are NES palette indices — $00-$3F,
+// the 2C02's own colour numbers; $0F is black, $30 white, row $0x dark
+// through row $3x pale — not RGB and not the Commodore/Atari values.
+//
+// The CPU cannot read the PPU's mask register back, so `renderingEnabled`
+// below is this module's own record of having switched rendering on: it
+// is what lets setColors() lay the frame exactly once, on the call that
+// is by construction the last moment a large VRAM write is free.
+
+let renderingEnabled: u8 = 0;
+
+// `count` consecutive nametable cells from `address`, one PPUADDR set and
+// then PPUDATA's auto-increment — the cheap way to write a run.
+function fillRun(address: usmallint, count: usmallint, value: utinyint): void {
+    setVramAddress(address);
+    for (let i: usmallint = 0; i < count; i++) {
+        memory.write(0x2007, value);
+    }
+}
+
+// The drawn border: rows 0-1 and 28-29 in full, columns 0-1 and 30-31 of
+// every row between, all tile $80 (solid colour index 2 — see font.s).
+// Then the 64-byte attribute table at $23C0, zeroed: palette 0 everywhere.
+function layFrame(): void {
+    fillRun(0x2000, 64, 0x80);
+    fillRun(0x2380, 64, 0x80);
+    for (let row: usmallint = 2; row < 28; row++) {
+        fillRun(0x2000 + row * 32, 2, 0x80);
+        fillRun(0x2000 + row * 32 + 30, 2, 0x80);
+    }
+    fillRun(0x23C0, 64, 0x00);
+}
+
+// Switch the picture on, the first time anything asks for one: the frame
+// and attribute table go in with rendering off (a few hundred VRAM
+// writes, no vblank budget to fit), the text palette entry is set, and
+// rendering starts at the next vertical blank — switching it on mid-frame
+// would draw the rest of that frame from wherever the PPU's address
+// register sits. Every later call returns at once.
+function showPicture(): void {
+    if (renderingEnabled == 1) {
+        return;
+    }
+    layFrame();
+    setVramAddress(0x3F01);
+    memory.write(0x2007, 0x30); // $3F01: text — white
+    resetScroll();
+    while (memory.read(0x2002) < 128) {
+    }
+    renderingEnabled = 1;
+    // PPUMASK: bit 3 shows the background, bit 1 shows it in the leftmost
+    // 8 pixels too — otherwise column 0, the outer edge of the frame, would
+    // be clipped to the backdrop colour. Sprites stay off.
+    memory.write(0x2001, 0x0A);
+}
+
+// One palette entry. With the picture on it goes through the write queue
+// and lands at the next vertical blank, like text (see index.8bs); with
+// the picture off the PPU is free and it is written now.
+function setPalette(entry: usmallint, color: utinyint): void {
+    if (renderingEnabled == 1) {
+        queueRun(entry);
+        queueByte(color);
+        return;
+    }
+    setVramAddress(entry);
+    memory.write(0x2007, color);
+    resetScroll();
+}
+
+export namespace screen {
+    function setColors(border: u8, background: u8): void {
+        setPalette(0x3F00, background); // $3F00: the universal backdrop
+        setPalette(0x3F02, border);     // $3F02: the frame tile
+        showPicture();
+    }
+
+    // `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 {
+        // The nametable can only be filled in bulk with the picture off.
+        // Before the first call that shows it, it already is; after, this
+        // switches it off, fills, and switches it back on at the next
+        // vertical blank — one dark frame, what every NES game does on a
+        // scene change. Cells are the 28x26 area inside the frame; tile 32
+        // is the blank, as putChar's space is.
+        let wasShowing: utinyint = renderingEnabled;
+        if (wasShowing == 1) {
+            memory.write(0x2001, 0x00);
+            renderingEnabled = 0; // the PPU is free until this switches it back on
+        }
+        nesVerticalBlank(); // whatever was printed before this, with the PPU free
+        if (border != BorderColor.KEEP) {
+            setPalette(0x3F02, border);
+        }
+        if (background != BackgroundColor.KEEP) {
+            setPalette(0x3F00, background);
+        }
+        for (let row: usmallint = 2; row < 28; row++) {
+            fillRun(0x2000 + row * 32 + 2, 28, 32);
+        }
+        resetScroll();
+        if (wasShowing == 1) {
+            while (memory.read(0x2002) < 128) {
+            }
+            renderingEnabled = 1;
+            memory.write(0x2001, 0x0A);
+        } else {
+            showPicture();
+        }
+    }
+
+    function setBackground(background: u8): void {
+        setPalette(0x3F00, background);
+        showPicture();
+    }
+
+    function setBorder(border: u8): void {
+        setPalette(0x3F02, border);
+        showPicture();
+    }
+}
+
+// ---- 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 2C02
+// palette indices, by the hue columns of NESdev's palette chart ($x2 blue,
+// $x4 purple, $x6 red, $x8 yellow, $xA green, $xC cyan; $0F black, $30
+// white), at the mid-brightness row $1x where the hue is unmistakable,
+// except cyan and yellow, whose $1x entries are too dark to read as their
+// names and so come from row $2x. A program that wants a colour not named
+// here passes its own index to setColors() directly. Not visually verified
+// under FCEUX by this project; the chart is NESdev's.
+
+export namespace BorderColor {
+    const BLACK: utinyint = 0x0F;
+    const WHITE: utinyint = 0x30;
+    const RED: utinyint = 0x16;
+    const CYAN: utinyint = 0x2C;
+    const PURPLE: utinyint = 0x14;
+    const GREEN: utinyint = 0x1A;
+    const BLUE: utinyint = 0x12;
+    const YELLOW: utinyint = 0x28;
+    // 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 = 0x0F;
+    const WHITE: utinyint = 0x30;
+    const RED: utinyint = 0x16;
+    const CYAN: utinyint = 0x2C;
+    const PURPLE: utinyint = 0x14;
+    const GREEN: utinyint = 0x1A;
+    const BLUE: utinyint = 0x12;
+    const YELLOW: utinyint = 0x28;
+    // 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,185 @@
+// @8bitscript/nes/text — the NES'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 NES. Built on the PPU port protocol
+// @8bitscript/nes exports — read that file first for the two VRAM rules
+// this one lives by. 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 { queueRun, queueByte } from "./index.8bs";
+
+// ---- text: the character set is ours to ship --------------------------
+//
+// A Commodore or Atari `text.putChar` writes one byte into screen memory
+// and a character ROM in the machine turns it into pixels. The NES has no
+// character ROM: the PPU fetches every 8x8 tile pattern from the cartridge,
+// so a cartridge that shows text must carry its own. This package does —
+// native/6502/font.s, an 8 KiB CHR-ROM listed in package.json's
+// "8bitscript".native and linked into the .nes image by the 6502 backend
+// (it rides along with every import of this package, its entry or any of
+// its subpaths) — laid out so that tile index == ASCII code.
+// `putChar(cell, 65)` therefore draws an 'A' with no translation table.
+// Space, digits, A-Z and `! , - . : ?` have glyphs; other codes in $20-$5F
+// are blank tiles. Reverse video of that range lives at ASCII+128 ($A0-$DF)
+// so `text.setReverse` is the same `code + 128` as on the Commodores. Tile
+// $80 is the solid frame, not a reverse copy, and +128 of a portable
+// character never lands on it. That set — upper case only — is what every
+// machine's putChar takes, precisely because it is what this font has: the
+// portable character set is the smallest one any target can show.
+//
+// The grid is the area inside the frame screen.8bs draws (see there):
+// 28 columns by 26 rows, 728 cells, cell 0 at nametable row 2, column 2,
+// each row 32 bytes apart in the nametable — cell `n` is nametable address
+// $2000 + (2 + n / 28) * 32 + 2 + n % 28. Nothing shows until
+// screen.setColors() has switched rendering on; until then, writes here
+// are free of any vblank budget (rule 2 in @8bitscript/nes), which is why
+// a program clears and labels first and sets colours last. putColor exists
+// so portable code still compiles and does nothing: the PPU has no
+// per-cell colour — the nearest thing, the attribute table, chooses a
+// palette per 32x32-pixel block, and every block here is palette 0.
+
+// ---- 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
+// nametable address without dividing, and a run of text lets the PPU 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
+
+// Reverse video is ASCII+128: the font ships inverted copies of $20-$5F
+// at $A0-$DF. Tile $80 is the drawn border and is not a reverse copy, so
+// the +128 of a portable character never lands on it. A reverse space is
+// a solid block in the text colour.
+function toTile(code: utinyint): utinyint {
+    if (currentReverse) {
+        return code + 128;
+    }
+    return code;
+}
+
+// The nametable address of a cell — row `cell / 28`, column the rest — and
+// the column back, for a caller that walks on from there. Eight-bit
+// arithmetic only, and no division or multiplication: LLVM-MOS links a
+// 250-byte routine for a 16-bit divide, turns a counted-subtraction loop
+// into one, and calls a 300-cycle multiply for `x * 147` — none of which
+// fits the vertical blank this runs in. A quarter of the cell fits a byte
+// (below 728, q < 182); q / 8 + q / 64 is q / 7 or one or two short, and
+// what is left over says which. Verified for every cell. It opens a run
+// in the package's write queue at that address (see index.8bs: nothing
+// here touches the PPU; waitFrame() delivers the queue in vertical
+// blank), and the run's bytes land in consecutive cells of the row.
+function locate(cell: usmallint): utinyint {
+    let q: utinyint = cell / 4;
+    let row: utinyint = q / 8 + q / 64;
+    let rest: utinyint = q - row * 8 + row; // q - row * 7, without the multiply
+    if (rest >= 7) {
+        rest = rest - 7;
+        row++;
+    }
+    if (rest >= 7) {
+        rest = rest - 7;
+        row++;
+    }
+    let col: utinyint = rest * 4 + cell % 4;
+    queueRun(0x2042 + row * 32 + col);
+    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 = 728; // 28 columns x 26 rows, inside the frame
+    const COLUMNS: utinyint = 28; // cells per row, so cell = y * text.COLUMNS + x
+
+    function putChar(cell: usmallint, code: utinyint): void {
+        locate(cell);
+        queueByte(toTile(code));
+    }
+
+    function putColor(cell: usmallint, color: utinyint): void {
+        // Deliberately empty — see above.
+    }
+
+    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++) {
+            queueByte(toTile(s[i]));
+            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) {
+                queueByte(toTile(digit));
+                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 NES text grid has no per-cell colour, so the
+// names are here for a program that compiles everywhere and their values
+// go nowhere.
+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;
+}