@8bitscript/vic20 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,256 @@
+{
+  "name": "@8bitscript/vic20",
+  "version": "0.1.0",
+  "description": "VIC-20 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",
+      "./input": "./src/input.8bs",
+      "./pointer": "./src/pointer.8bs",
+      "./keyboard": "./src/keyboard.8bs",
+      "./keys": "./src/keys.8bs"
+    },
+    "hardware": {
+      "facts": {
+        "video.columns": 22,
+        "video.rows": 23,
+        "video.cellWidth": 8,
+        "video.cellHeight": 8,
+        "video.palette": 16,
+        "video.cellColors": 2,
+        "video.colorPerCell": true,
+        "video.glyphs": 256,
+        "video.blockWidth": 2,
+        "video.blockHeight": 2,
+        "video.bitmap": false,
+        "video.layers": 1,
+        "video.scroll": false,
+        "video.sprites": 0,
+        "video.spritesPerLine": 0,
+        "video.spriteWidth": 0,
+        "video.spriteHeight": 0,
+        "video.spriteColors": 0,
+        "video.frameRate": 60,
+        "audio.voices": 4,
+        "audio.noise": true,
+        "audio.envelope": false,
+        "audio.filter": false,
+        "audio.pcm": false,
+        "audio.volume": false,
+        "audio.entropy": false,
+        "input.keyboard": true,
+        "input.joysticks": 1,
+        "input.pads": 0,
+        "input.mouse": false,
+        "input.paddles": false,
+        "storage.save": true,
+        "memory.ram": 3583,
+        "memory.banked": false,
+        "memory.bankedKib": 0,
+        "storage.kib": 164
+      },
+      "options": {
+        "ram": {
+          "label": "RAM expansion",
+          "default": "none",
+          "values": {
+            "none": {
+              "label": "Unexpanded (3583 bytes for the program)",
+              "build": {
+                "defsym": {
+                  "__memory_expansion": 0
+                }
+              },
+              "run": {
+                "xvic": [
+                  "-memory",
+                  "none"
+                ]
+              },
+              "facts": {
+                "memory.ram": 3583
+              }
+            },
+            "3k": {
+              "label": "3K (VIC-1210): $0400-$0FFF",
+              "tag": "3k",
+              "build": {
+                "defsym": {
+                  "__memory_expansion": 3
+                }
+              },
+              "run": {
+                "xvic": [
+                  "-memory",
+                  "3k"
+                ]
+              },
+              "facts": {
+                "memory.ram": 6655
+              }
+            },
+            "8k": {
+              "label": "8K: screen moves to $1000",
+              "tag": "expanded",
+              "build": {
+                "defsym": {
+                  "__memory_expansion": 8
+                }
+              },
+              "run": {
+                "xvic": [
+                  "-memory",
+                  "8k"
+                ]
+              },
+              "facts": {
+                "memory.ram": 11775
+              }
+            },
+            "16k": {
+              "label": "16K: screen moves to $1000",
+              "tag": "expanded",
+              "build": {
+                "defsym": {
+                  "__memory_expansion": 16
+                }
+              },
+              "run": {
+                "xvic": [
+                  "-memory",
+                  "16k"
+                ]
+              },
+              "facts": {
+                "memory.ram": 19967
+              }
+            },
+            "24k": {
+              "label": "24K: screen moves to $1000",
+              "tag": "expanded",
+              "build": {
+                "defsym": {
+                  "__memory_expansion": 24
+                }
+              },
+              "run": {
+                "xvic": [
+                  "-memory",
+                  "24k"
+                ]
+              },
+              "facts": {
+                "memory.ram": 28159
+              }
+            }
+          }
+        },
+        "port1": {
+          "label": "Control port 1",
+          "default": "joystick",
+          "values": {
+            "none": {
+              "label": "Nothing plugged in",
+              "run": {
+                "xvic": [
+                  "-controlport1device",
+                  "0"
+                ]
+              }
+            },
+            "joystick": {
+              "label": "Joystick",
+              "run": {
+                "xvic": [
+                  "-controlport1device",
+                  "1"
+                ]
+              }
+            },
+            "paddles": {
+              "label": "Paddles",
+              "run": {
+                "xvic": [
+                  "-controlport1device",
+                  "2"
+                ]
+              },
+              "facts": {
+                "input.paddles": true
+              }
+            },
+            "mouse1351": {
+              "label": "Commodore 1351 mouse",
+              "run": {
+                "xvic": [
+                  "-controlport1device",
+                  "3",
+                  "-mouse"
+                ]
+              },
+              "facts": {
+                "input.mouse": true
+              }
+            }
+          }
+        },
+        "drive": {
+          "label": "Disk drive",
+          "default": "1541",
+          "values": {
+            "1541": {
+              "label": "1541 (170K disk)",
+              "facts": {
+                "storage.save": true,
+                "storage.kib": 164
+              },
+              "tag": null
+            },
+            "1581": {
+              "label": "1581 (800K disk)",
+              "facts": {
+                "storage.save": true,
+                "storage.kib": 783
+              },
+              "tag": null
+            },
+            "none": {
+              "label": "No drive (tape or nothing)",
+              "facts": {
+                "storage.save": false,
+                "storage.kib": 0
+              },
+              "tag": null
+            }
+          }
+        }
+      },
+      "presets": {
+        "unexpanded": {
+          "ram": "none"
+        },
+        "3k": {
+          "ram": "3k"
+        },
+        "8k": {
+          "ram": "8k"
+        },
+        "16k": {
+          "ram": "16k"
+        },
+        "24k": {
+          "ram": "24k"
+        }
+      }
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/geometry.8bs

@@ -0,0 +1,36 @@
+// @8bitscript/vic20 — where the screen is, for the unexpanded and 3K VIC-20.
+//
+// The VIC-20's screen moves with its memory. Unexpanded (and with a 3K
+// expansion, which fills $0400-$0FFF and leaves everything above alone)
+// the KERNAL puts the 22x23 screen matrix at $1E00 with its colour nybbles
+// at $9600, and BASIC starts at $1001. With 8K or more the KERNAL moves the
+// screen down to $1000 and colour RAM to $9400, so that $1200 upward is one
+// contiguous run of BASIC RAM — which is why the SDK loads an 8K+ program at
+// $1201 (mos-platform/vic20/lib/link.ld). This file is the unexpanded/3K
+// geometry; `geometry.vic20.expanded.8bs` beside it is the 8K-and-up one,
+// read by a build whose hardware carries the `expanded` tag — the tag the
+// package's catalog gives the 8k, 16k and 24k values of its `ram` option
+// (package.json, "8bitscript".hardware), one word for the one thing they
+// share. text.8bs and screen.8bs are written once, against these numbers
+// (docs/packages.md, "System-specific files").
+//
+// Two of these are the VIC's, not the KERNAL's, and the package writes one
+// of them itself: MEMORY_POINTER_UPPERCASE is what text.8bs stores in $9005
+// before every run of text — bits 4-7 the screen base, bits 0-3 the
+// upper-case character ROM at $8000 — $F0 for a screen at $1E00, $C0 for
+// one at $1000 (POKE 36869,240 and POKE 36869,192 in the Programmer's
+// Reference Guide). The screen's address bit 9 and the colour RAM base
+// both come from $9002 bit 7, which the package leaves as the KERNAL set
+// it at boot from the RAM it found. So the profile has to match the
+// machine: a `--profile 8k` build on an unexpanded VIC-20 would write $C0
+// to a VIC whose $9002 still says $1E00, and draw nowhere useful. `8bs run`
+// launches xvic with the matching `-memory`, so the emulator always agrees.
+
+export namespace Video {
+    const SCREEN: usmallint = 0x1E00; // screen matrix: one screen code per cell
+    const COLOR: usmallint = 0x9600; // colour RAM: one nybble per cell, same cell index
+    const MEMORY_POINTER_UPPERCASE: utinyint = 0xF0; // $9005: this screen, upper-case ROM
+    const COLUMNS: utinyint = 22;
+    const ROWS: utinyint = 23;
+    const CELL_COUNT: usmallint = 506; // COLUMNS * ROWS
+}

package/src/geometry.vic20.expanded.8bs

@@ -0,0 +1,20 @@
+// @8bitscript/vic20 — where the screen is, with 8K or more of expansion.
+//
+// The `expanded` version of geometry.8bs (see that file for the whole
+// story): with 8K or more the KERNAL moves the screen matrix to $1000 and
+// colour RAM to $9400 so BASIC RAM runs unbroken from $1200, and the SDK
+// loads the program at $1201. $9005's screen nybble becomes $C0 (POKE
+// 36869,192). One file serves the 8k, 16k and 24k values of the `ram`
+// option because the catalog (package.json, "8bitscript".hardware) gives
+// all three the same `expanded` tag: where the screen is depends on
+// whether there is 8K or more, not on how much more, and a tag names
+// exactly the thing a file differs on.
+
+export namespace Video {
+    const SCREEN: usmallint = 0x1000; // screen matrix: one screen code per cell
+    const COLOR: usmallint = 0x9400; // colour RAM: one nybble per cell, same cell index
+    const MEMORY_POINTER_UPPERCASE: utinyint = 0xC0; // $9005: this screen, upper-case ROM
+    const COLUMNS: utinyint = 22;
+    const ROWS: utinyint = 23;
+    const CELL_COUNT: usmallint = 506; // COLUMNS * ROWS
+}

package/src/index.8bs

@@ -0,0 +1,57 @@
+// @8bitscript/vic20 — VIC-20 target support: the hardware underneath.
+//
+// The module entry point named by the "8bitscript".entry field in this
+// package's package.json, resolved and linked for:
+//
+//     import { vicColor, memoryPointer } from "@8bitscript/vic20";
+//
+// The surface is the hardware, one register at a time. 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 import these
+// registers and are built on nothing else. A project that imports THIS
+// package has declared itself VIC-20 specific.
+
+// $900F, the VIC chip's screen/colour register. Bits verified against the
+// VIC-20's own hardware map, not inferred from a BASIC POKE example:
+//
+//   bits 4-7  background colour (16 values)
+//   bit  3    normal/inverted video (1 = normal)
+//   bits 0-2  border colour (8 values — the VIC only gives border 3 bits)
+@address(0x900F)
+export let vicColor: volatile<u8>;
+
+// $9005, the VIC's memory pointer (`addr` in llvm-mos-sdk's _vic.h): bits
+// 4-7 the screen base, bits 0-3 the character set base. $F0 is screen $1E00
+// with the upper-case/graphics character ROM at $8000 — the power-on value
+// (POKE 36869,240 in the Programmer's Reference Guide), where $F2 is the
+// lower-case ROM at $8800.
+@address(0x9005)
+export let memoryPointer: volatile<u8>;
+
+// ---- the VIAs ($9110, $9120): the control port and the keyboard -------------
+//
+// The VIC-20 splits one joystick across two chips, which is the single
+// most surprising thing about input on this machine. VIA1's port A carries
+// up, down, left and fire; **right is VIA2 port B bit 7** — a line that is
+// otherwise a keyboard *column output*. So reading it means turning that
+// one bit around to an input and back, which is what
+// `@8bitscript/vic20/input` does and why it cannot simply read a port.
+//
+// The keyboard is VIA2: port B selects columns (outputs, DDRB $FF at boot)
+// and port A reads the rows of the selected column (inputs, DDRA $00).
+//
+// Verified against VICE's `vic20via1.c` and `vic20via2.c` — see
+// ../AGENTS.md, which records the port bits and the boot-time direction
+// registers this package relies on.
+@address(0x9111)
+export let via1PortA: volatile<u8>;
+@address(0x9120)
+export let via2PortB: volatile<u8>;
+@address(0x9121)
+export let via2PortA: volatile<u8>;
+@address(0x9122)
+export let via2DirectionB: volatile<u8>;
+@address(0x9123)
+export let via2DirectionA: volatile<u8>;

package/src/input.8bs

@@ -0,0 +1,179 @@
+// @8bitscript/vic20/input — the VIC-20 behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.vic20 in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file on a VIC-20. The machine-level layers underneath —
+// ./keyboard.8bs, ./keys.8bs — stay available to a program that wants the
+// matrix itself.
+//
+// ---- one joystick split across two chips ---------------------------------
+//
+// This is the machine where reading a joystick is not reading a port. Up,
+// down, left and fire are VIA1 port A ($9111) bits 2, 3, 4 and 5 — a 0 bit
+// where a switch is closed, as everywhere. **Right is VIA2 port B bit 7**
+// ($9120), which is otherwise a keyboard *column output*. So reading right
+// means turning that one bit around to an input, reading it, and putting
+// it back an output before anything else touches the keyboard lines — and
+// it has to happen *after* `keyboard.scan()` below, which is the thing
+// actually driving those seven other columns each frame; read the joystick
+// first and scan() would find every column selected but the last, and read
+// "right" as though nothing else had touched the port.
+//
+// Verified against VICE's `vic20via1.c` and `vic20via2.c`; ../AGENTS.md
+// records the bits and the boot-time direction registers.
+//
+// ---- the keyboard, and the cursor keys' two directions --------------------
+//
+// Like the C64, this keyboard has two cursor keys, not four:
+// `CURSOR_LEFT_RIGHT` and `CURSOR_UP_DOWN`, with SHIFT reversing each — so
+// left is SHIFT plus the right key, and up is SHIFT plus the down key,
+// which is what the machine actually has rather than four keys it does
+// not. `Key`'s table (./keys.8bs) is checked key for key against VICE's
+// own positional keyboard map (packages/compiler/test/vic20-keys.test.mjs)
+// rather than recalled from memory, per the root AGENTS.md's rule to
+// verify hardware facts before writing them down.
+//
+// **A mouse.** `--hardware port1=mouse1351` sets `input.mouse` on this
+// machine, but a 1351 here would read through the VIC's own analogue lines
+// at $9008/$9009, not a SID's — a different driver from the C64's, and one
+// nobody has written or measured. `pointer()` is false rather than
+// hopeful.
+//
+// ---- edges, not levels ---------------------------------------------------
+//
+// Every answer is edge-triggered: true on the one frame the press begins.
+// `poll()` once a frame, right after waitFrame().
+import { via1PortA, via2PortB, via2DirectionB } from "./index.8bs";
+import { keyboard } from "./keyboard.8bs";
+import { Key } from "./keys.8bs";
+
+// VIA1 port A's four switches, and the odd one out on VIA2.
+const JOY_UP: utinyint = 4;
+const JOY_DOWN: utinyint = 8;
+const JOY_LEFT: utinyint = 16;
+const JOY_FIRE: utinyint = 32;
+const JOY_RIGHT: utinyint = 128; // VIA2 port B bit 7
+
+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: no pointer to give a ceiling to.
+    function begin(): void {
+    }
+
+    function poll(): void {
+        // First, so the other seven keyboard columns are already driven
+        // for this frame before the joystick-right read below borrows
+        // bit 7 of the same port.
+        keyboard.scan();
+
+        // The four on VIA1, inverted once so a 1 bit means pushed.
+        let stick: utinyint = via1PortA ^ 0xFF;
+
+        // Right, on a line that is normally a keyboard column output.
+        // Turn bit 7 around, read it, put it back — leaving the other
+        // seven columns exactly as they were, because the KERNAL is not
+        // the only thing that drives them.
+        via2DirectionB = via2DirectionB & 0x7F;
+        let rightPushed: bool = (via2PortB & JOY_RIGHT) == 0;
+        via2DirectionB = via2DirectionB | 0x80;
+
+        before = held;
+        held = 0;
+
+        if ((stick & JOY_LEFT) != 0) {
+            held = held | Edge.LEFT;
+        }
+        if (rightPushed) {
+            held = held | Edge.RIGHT;
+        }
+        if ((stick & JOY_UP) != 0) {
+            held = held | Edge.UP;
+        }
+        if ((stick & JOY_DOWN) != 0) {
+            held = held | Edge.DOWN;
+        }
+        if ((stick & JOY_FIRE) != 0) {
+            held = held | Edge.CONFIRM;
+        }
+
+        // The two cursor keys and SHIFT, which is what "four directions"
+        // is on this keyboard — or'd on top of the joystick, same as the
+        // C64: a program should not care which the user reached for.
+        let shifted: bool = keyboard.pressed(Key.SHIFT_LEFT) || keyboard.pressed(Key.SHIFT_RIGHT);
+        if (keyboard.pressed(Key.CURSOR_LEFT_RIGHT)) {
+            if (shifted) {
+                held = held | Edge.LEFT;
+            } else {
+                held = held | Edge.RIGHT;
+            }
+        }
+        if (keyboard.pressed(Key.CURSOR_UP_DOWN)) {
+            if (shifted) {
+                held = held | Edge.UP;
+            } else {
+                held = held | Edge.DOWN;
+            }
+        }
+        if (keyboard.pressed(Key.RETURN)) {
+            held = held | Edge.CONFIRM;
+        }
+        if (keyboard.pressed(Key.RUN_STOP)) {
+            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;
+    }
+
+    function pointer(): bool {
+        return false;
+    }
+
+    function pointerCell(): usmallint {
+        return 0;
+    }
+
+    function pointerButton(): bool {
+        return false;
+    }
+}

package/src/keyboard.8bs

@@ -0,0 +1,80 @@
+// @8bitscript/vic20/keyboard — the VIC-20's keyboard matrix, one snapshot a
+// frame.
+//
+// Named by "8bitscript".exports["./keyboard"] in this package's package.json:
+//
+//     import { keyboard } from "@8bitscript/vic20/keyboard";
+//     import { Key } from "@8bitscript/vic20/keys";
+//
+// This is hardware-level, VIC-20-only surface — the layer the portable
+// input capability is built on: `@8bitscript/vic20/input` reads this file
+// and @8bitscript/input resolves to that, the way ./text.8bs is the layer
+// under @8bitscript/text. Importing it makes a program VIC-20-specific.
+// It keeps no key buffer and decodes no PETSCII; it answers "is this key
+// down now", which is what a game loop asks.
+//
+// ---- how the matrix works -----------------------------------------------
+//
+// Eight columns by eight rows, on VIA2 alone — ../index.8bs and
+// ../AGENTS.md (verified against VICE's `vic20via2.c`): port B selects a
+// column (DDRB $FF at boot, all eight lines outputs), port A reads that
+// column's eight keys (DDRA $00, inputs), a 0 bit where a key is down.
+// `scan()` writes both direction registers itself, so it does not depend
+// on what ran before, and drives every column exactly once — the KERNAL's
+// own IRQ scan (packages/vic20/AGENTS.md: a free-running ~60 Hz timer, not
+// locked to the frame) would otherwise land its own column select between
+// this scan's write and read, which is one reason the frame runtime
+// starts a VIC-20 program with interrupts held off.
+//
+// `scan()` reads all eight columns into `state`, once a frame, right after
+// waitFrame() returns; every question after that reads the snapshot. It
+// leaves port B at $FF — no column selected — which is the state
+// @8bitscript/vic20/input's joystick-right read needs: VIA2 port B bit 7
+// doubles as that line, and turning it around to an input reads correctly
+// only once the keyboard scan is no longer driving it low for some other
+// column. Call `keyboard.scan()` first and read the joystick second, both
+// once a frame.
+//
+// Ghosting is the same hazard it is on every unshifted matrix: three keys
+// down can read as four. Two keys are always safe.
+import { via2PortA, via2PortB, via2DirectionA, via2DirectionB } from "./index.8bs";
+
+// The last scan, one byte per column, a 1 bit where a key is down (the
+// port's active-low rows inverted once, here, so nothing else has to
+// think about it). All zero until the first scan.
+let state: array<utinyint, 8>;
+
+// The column-select byte for each column, and the row masks — indexed
+// rather than shifted, as `1 << n` with a variable n is a loop on the 6502.
+const COLUMN_SELECT: array<utinyint, 8> = [254, 253, 251, 247, 239, 223, 191, 127];
+const ROW_BIT: array<utinyint, 8> = [1, 2, 4, 8, 16, 32, 64, 128];
+
+export namespace keyboard {
+    const COLUMNS: utinyint = 8;
+    const ROWS: utinyint = 8;
+
+    // Read all eight columns into the snapshot. Once a frame, right after
+    // waitFrame(), before reading the joystick's right line.
+    function scan(): void {
+        via2DirectionB = 0xFF;
+        via2DirectionA = 0x00;
+        for (let select: utinyint = 0; select < 8; select++) {
+            via2PortB = COLUMN_SELECT[select];
+            state[select] = via2PortA ^ 0xFF;
+        }
+        via2PortB = 0xFF;
+    }
+
+    // Is this key down in the last scan? `key` is a `Key.*` value from
+    // @8bitscript/vic20/keys — `select * 8 + row` in the matrix.
+    function pressed(key: utinyint): bool {
+        return (state[key >> 3] & ROW_BIT[key & 7]) != 0;
+    }
+
+    // The last scan's eight rows of one column, a 1 bit per key down:
+    // for code that wants a whole column at once (an "any key" test over
+    // all eight, a ghosting check).
+    function column(index: utinyint): utinyint {
+        return state[index];
+    }
+}

package/src/keys.8bs

@@ -0,0 +1,139 @@
+// @8bitscript/vic20/keys — the keyboard matrix, key by key.
+//
+// Named by "8bitscript".exports["./keys"] in this package's package.json, for
+//
+//     import { keyboard } from "@8bitscript/vic20/keyboard";
+//     import { Key } from "@8bitscript/vic20/keys";
+//
+//     if (keyboard.pressed(Key.SPACE)) { ... }
+//
+// Each value is `select * 8 + row` in VIA2's matrix (see ./keyboard.8bs):
+// `select` is which of VIA2 port B's eight column-select lines was driven
+// low to reach this key, `row` the bit of VIA2 port A that reads low —
+// ../AGENTS.md, "Keyboard: VIA2 port B selects columns (output), port A
+// reads rows against the selected columns" (verified there against
+// vic20via2.c `read_pra`: port B is the column mask, `rev_keyarr[column]`
+// the row bits). One matrix on every VIC-20 ever made, expanded or not.
+//
+// Source: the matrix diagram in VICE's own vic20/gtk3_pos.vkm (reproduced
+// below), checked here key for key against that file,
+// /opt/homebrew/share/vice/VIC20/gtk3_pos.vkm. Each line there is
+// `keysym row column shiftflag`: VICE's first number is the **row** (VIA2
+// port A bit), its second the **column** (VIA2 port B bit). `keyboard.scan()`
+// indexes `state[column]` with row bits, so a Key is `column * 8 + row`,
+// not `row * 8 + column`. The C64 table can use VICE's pair in file order
+// because that machine's gtk3_pos.vkm writes the *column* first; copying
+// that convention here looked up every key in the transposed cell
+// (2048 on xvic, 2026-09-07: host Right lit port-B column 2 / port-A bit 7
+// — Key 23 — while this table named that position 58).
+// packages/compiler/test/vic20-keys.test.mjs repeats the check when the
+// keymap is present.
+//
+//       +------+------+------+------+------+------+------+------+
+//       |sel. 0|sel. 1|sel. 2|sel. 3|sel. 4|sel. 5|sel. 6|sel. 7|
+// +-----+------+------+------+------+------+------+------+------+
+// |row 0| 1 !  |A_LEFT| CTRL | R/S  |SPACE |  C=  |  Q   | 2 "  |
+// +-----+------+------+------+------+------+------+------+------+
+// |row 1| 3 #  |  W   |  A   |S_LEFT|  Z   |  S   |  E   | 4 $  |
+// +-----+------+------+------+------+------+------+------+------+
+// |row 2| 5 %  |  R   |  D   |  X   |  C   |  F   |  T   | 6 &  |
+// +-----+------+------+------+------+------+------+------+------+
+// |row 3| 7 '  |  Y   |  G   |  V   |  B   |  H   |  U   | 8 (  |
+// +-----+------+------+------+------+------+------+------+------+
+// |row 4| 9 )  |  I   |  J   |  N   |  M   |  K   |  O   |  0   |
+// +-----+------+------+------+------+------+------+------+------+
+// |row 5|  +   |  P   |  L   | , <  | . >  | : [  |  @   |  -   |
+// +-----+------+------+------+------+------+------+------+------+
+// |row 6|POUND |  *   | ; ]  | / ?  |S_RGHT|  =   |A_UP  | HOME |
+// +-----+------+------+------+------+------+------+------+------+
+// |row 7| DEL  |RETURN|C_L/R |C_U/D |  F1  |  F3  |  F5  |  F7  |
+// +-----+------+------+------+------+------+------+------+------+
+//
+// Two keys are not in it: RESTORE is wired to the CPU's NMI line (VIA1's
+// CA1, ../AGENTS.md), and SHIFT LOCK is the left SHIFT key's own wire,
+// held down (VICE's `Caps_Lock` maps to the same position as `Shift_L`).
+//
+// A key that also exists on the C64 or PET has the same name here —
+// letters, `DIGIT_n`, SPACE, RETURN, HOME, DELETE, both shifts, the arrows
+// and the shared punctuation — so a program that sticks to those names
+// reads the same across the Commodores it runs on. `CURSOR_LEFT_RIGHT` and
+// `CURSOR_UP_DOWN` are named for what this keyboard actually has: one key
+// per pair, not four, with SHIFT reversing each — the same shape as the
+// C64's `CURSOR_RIGHT`/`CURSOR_DOWN`, under different names because they
+// are not the same two directions unshifted (this machine's un-shifted
+// pair is right and down, matching the C64's).
+
+export namespace Key {
+    // select 0 — VIA2 port B bit 0
+    const DIGIT_1: utinyint = 0;
+    const DIGIT_3: utinyint = 1;
+    const DIGIT_5: utinyint = 2;
+    const DIGIT_7: utinyint = 3;
+    const DIGIT_9: utinyint = 4;
+    const PLUS: utinyint = 5;
+    const POUND: utinyint = 6; // £
+    const DELETE: utinyint = 7; // INST/DEL
+    // select 1
+    const LEFT_ARROW: utinyint = 8; // the "<-" key left of DIGIT_1, not a cursor key
+    const W: utinyint = 9;
+    const R: utinyint = 10;
+    const Y: utinyint = 11;
+    const I: utinyint = 12;
+    const P: utinyint = 13;
+    const ASTERISK: utinyint = 14;
+    const RETURN: utinyint = 15;
+    // select 2
+    const CTRL: utinyint = 16;
+    const A: utinyint = 17;
+    const D: utinyint = 18;
+    const G: utinyint = 19;
+    const J: utinyint = 20;
+    const L: utinyint = 21;
+    const SEMICOLON: utinyint = 22;
+    const CURSOR_LEFT_RIGHT: utinyint = 23; // unshifted: right; shifted: left
+    // select 3
+    const RUN_STOP: utinyint = 24;
+    const SHIFT_LEFT: utinyint = 25; // also SHIFT LOCK
+    const X: utinyint = 26;
+    const V: utinyint = 27;
+    const N: utinyint = 28;
+    const COMMA: utinyint = 29;
+    const SLASH: utinyint = 30;
+    const CURSOR_UP_DOWN: utinyint = 31; // unshifted: down; shifted: up
+    // select 4
+    const SPACE: utinyint = 32;
+    const Z: utinyint = 33;
+    const C: utinyint = 34;
+    const B: utinyint = 35;
+    const M: utinyint = 36;
+    const PERIOD: utinyint = 37;
+    const SHIFT_RIGHT: utinyint = 38;
+    const F1: utinyint = 39; // shifted: F2
+    // select 5
+    const COMMODORE: utinyint = 40; // the C= key
+    const S: utinyint = 41;
+    const F: utinyint = 42;
+    const H: utinyint = 43;
+    const K: utinyint = 44;
+    const COLON: utinyint = 45;
+    const EQUALS: utinyint = 46;
+    const F3: utinyint = 47; // shifted: F4
+    // select 6
+    const Q: utinyint = 48;
+    const E: utinyint = 49;
+    const T: utinyint = 50;
+    const U: utinyint = 51;
+    const O: utinyint = 52;
+    const AT: utinyint = 53;
+    const UP_ARROW: utinyint = 54;
+    const F5: utinyint = 55; // shifted: F6
+    // select 7
+    const DIGIT_2: utinyint = 56;
+    const DIGIT_4: utinyint = 57;
+    const DIGIT_6: utinyint = 58;
+    const DIGIT_8: utinyint = 59;
+    const DIGIT_0: utinyint = 60;
+    const MINUS: utinyint = 61;
+    const HOME: utinyint = 62; // CLR/HOME
+    const F7: utinyint = 63; // shifted: F8
+}

package/src/pointer.8bs

@@ -0,0 +1,40 @@
+// @8bitscript/vic20/pointer — the VIC-20 behind @8bitscript/pointer.
+//
+// Every call here does nothing and `DRAWS` is false, and on this machine
+// that is the hardware's answer: **the VIC has no sprites.** There are no
+// movable objects to put an arrow in, so a cursor here would have to be a
+// character cell — which means putting back the cell it covered, and
+// @8bitscript/text can write a cell but not read one, so it cannot. A
+// redefined glyph moved a cell at a time is the shape such a cursor would
+// take, and it would be a different thing from the C64's pixel-precise
+// arrow rather than a poorer copy of it.
+//
+// The other half is missing too: @8bitscript/vic20/input reports no
+// pointer. The catalog offers `port1: mouse1351` and xvic accepts it, but
+// this repository has no 1351 driver for the VIC-20 and the hardware note
+// marks the 1351 on this machine *to verify* (see
+// packages/vic20/AGENTS.md). So there is nothing to draw and nowhere to
+// draw it from, in that order.
+//
+// It still has to exist: Studio and every other portable program links
+// @8bitscript/pointer, so a missing entry is not a program without a
+// cursor, it is a program that does not build for the VIC-20 — the machine
+// with the least room to spare, which is exactly why this file is
+// constants. `DRAWS` is a const and every function is empty, so a
+// program's `if (pointer.DRAWS)` folds away and LLVM deletes the calls.
+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,101 @@
+// @8bitscript/vic20/screen — the VIC-20'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 VIC-20: @8bitscript/screen's entry is
+// keyed by machine and delegates here. Built on the register @8bitscript/vic20
+// itself exports, one layer up from it. 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 { vicColor } from "./index.8bs";
+import { Video } from "./geometry.8bs";
+
+// ---- the screen: border and background --------------------------------------
+//
+// One packed register on the VIC: border in bits 0-2 (the VIC has eight
+// border colours, so the value is masked to them), background in bits 4-7,
+// bit 3 held at 1 for normal video. Both colours in one call because they
+// are one write here — and because on the NES and the X16 the two are
+// genuinely one operation (see those packages), so the portable surface is
+// the one every machine can honour.
+export namespace screen {
+    function setColors(border: u8, background: u8): void {
+        vicColor = (8 | (border & 7)) | (background << 4);
+    }
+
+    // `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);
+        }
+        for (let cell: usmallint = 0; cell < Video.CELL_COUNT; cell++) {
+            memory.write(Video.SCREEN + cell, 32); // 32: the space screen code
+        }
+    }
+
+    function setBackground(background: u8): void {
+        vicColor = (vicColor & 0x0F) | (background << 4);
+    }
+
+    function setBorder(border: u8): void {
+        vicColor = (vicColor & 0xF0) | 8 | (border & 7);
+    }
+}
+
+// ---- colour names ----------------------------------------------------------
+//
+// The border field only has 3 bits, so it can only reach the first 8 of the
+// VIC's 16 colours — `BorderColor` and `BackgroundColor` are two namespaces,
+// not one shared `Color`, because the hardware itself draws that line, not
+// an API design preference. Values and names match the VIC-20's own colour
+// numbering (POKE 36879 in the Programmer's Reference Guide). Those first
+// eight names — Black, White, Red, Cyan, Purple, Green, Blue, Yellow — are
+// the ones every machine's screen.8bs exports in both namespaces, each with
+// its own hardware's value, which is what lets a program say
+// `screen.setColors(BorderColor.BLUE, BackgroundColor.BLACK)` on any target.
+
+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;
+    // 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 LIGHT_ORANGE: utinyint = 9;
+    const PINK_RED: utinyint = 10;
+    const LIGHT_CYAN: utinyint = 11;
+    const LIGHT_PURPLE: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_YELLOW: 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,169 @@
+// @8bitscript/vic20/text — the VIC-20'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 VIC-20. Built on the registers
+// @8bitscript/vic20 exports. 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 { memoryPointer } from "./index.8bs";
+import { Video } from "./geometry.8bs";
+
+// The screen is addressed by flat cell index — a position is
+// `y * text.COLUMNS + x` — and these are the plainest things a text API
+// can be built from: poke one cell's character code, poke one cell's colour, and how many
+// cells the whole screen has. Whether a caller uses these to clear the
+// screen, lay out a label, or nothing at all is entirely up to the caller —
+// this package draws nothing on its own.
+//
+// Where the 22x23 screen and its colour nybbles are depends on the RAM the
+// machine has — $1E00/$9600 unexpanded or with 3K, $1000/$9400 with 8K or
+// more — and that is the build's `--profile` to say (VIC20_PROFILES in
+// packages/backend-6502). It reaches this file as ./geometry.8bs's `Video`
+// namespace, whose 8k/16k/24k twins the profile selects; nothing here
+// names an address.
+//
+// ---- character codes: ASCII in, screen codes out ----------------------------
+//
+// `text.putChar` takes ASCII on every machine — space (32), '0'-'9'
+// (48-57), 'A'-'Z' (65-90) and the punctuation `! , - . : ?` — upper case
+// only: that is the portable set, the characters every target's character
+// set has (the NES ships its own font, and that is what it has). The VIC
+// wants screen codes: in every Commodore character ROM codes 32-63 are
+// those same ASCII values, and 'A'-'Z' are 1-26, so asciiToScreenCode()
+// moves 64-95 down by 64 and leaves 32-63 alone.
+//
+// Whether 1-26 then LOOK like 'A'-'Z' or 'a'-'z' is the character set's
+// choice — the ROM's boot state, whatever ran before, a user's SHIFT+C= —
+// so this package owns the choice rather than inheriting one (LLVM-MOS's
+// libc used to flip the machine to lower-case before main() with a hidden
+// CHR$(14); packages/backend-6502's commodoreCharsetGuard() keeps that out
+// of the link). putChar()
+// selects the upper-case set, every call, through the VIC's memory pointer
+// (see @8bitscript/vic20's `memoryPointer`): one register write — of the
+// value that also names this profile's screen base, since $9005 holds
+// both — and "TICK" reads as TICK here the way it does on the NES, the
+// Atari, and the X16, none of which have a lower-case set to fall into.
+
+function asciiToScreenCode(code: utinyint): utinyint {
+    if (code >= 64 && code < 96) {
+        return code - 64;
+    }
+    return code;
+}
+
+// ---- 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: `place()` puts one character at one cell in the current
+// colour, and is all a run of text costs per character, with `prepare()` selecting the
+// upper-case set once for the run.
+// `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 a real ROM copy at codes 128-255.
+function toScreen(code: utinyint): utinyint {
+    let screen: utinyint = asciiToScreenCode(code);
+    if (currentReverse) {
+        screen = screen + 128;
+    }
+    return screen;
+}
+
+// What a run of text needs once, before its first character.
+function prepare(): void {
+    memoryPointer = Video.MEMORY_POINTER_UPPERCASE;
+}
+
+function place(cell: usmallint, code: utinyint): void {
+    memory.write(Video.SCREEN + cell, toScreen(code));
+    memory.write(Video.COLOR + cell, currentColor & 0x07); // bit 3 would make the cell multicolour
+}
+
+// ---- 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 = Video.CELL_COUNT; // 22 columns x 23 rows
+    const COLUMNS: utinyint = Video.COLUMNS; // cells per row, so cell = y * text.COLUMNS + x
+
+    function putChar(cell: usmallint, code: utinyint): void {
+        prepare();
+        memory.write(Video.SCREEN + cell, toScreen(code));
+    }
+
+    function putColor(cell: usmallint, color: utinyint): void {
+        memory.write(Video.COLOR + cell, color & 0x07);
+    }
+
+    function setColor(color: utinyint): void {
+        currentColor = color;
+    }
+
+    function setReverse(on: bool): void {
+        currentReverse = on;
+    }
+
+    function print(cell: usmallint, s: string): void {
+        prepare();
+        for (let i: utinyint = 0; i < s.length; i++) {
+            place(cell + i, s[i]);
+        }
+    }
+
+    function printNumber(cell: usmallint, value: usmallint, width: utinyint): void {
+        prepare();
+        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) {
+                place(cell + width - k, digit);
+            }
+            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;
+}