@8bitscript/web 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,63 @@
+{
+  "name": "@8bitscript/web",
+  "version": "0.1.0",
+  "description": "Browser target support for 8BitScript: the hardware underneath the portable APIs, where the hardware is a canvas.",
+  "license": "MIT",
+  "8bitscript": {
+    "entry": "./src/index.8bs",
+    "exports": {
+      "./screen": "./src/screen.8bs",
+      "./text": "./src/text.8bs",
+      "./input": "./src/input.8bs",
+      "./pointer": "./src/pointer.8bs"
+    },
+    "hardware": {
+      "facts": {
+        "video.columns": 40,
+        "video.rows": 25,
+        "video.cellWidth": 8,
+        "video.cellHeight": 8,
+        "video.palette": 16,
+        "video.cellColors": 2,
+        "video.colorPerCell": true,
+        "video.glyphs": 0,
+        "video.blockWidth": 0,
+        "video.blockHeight": 0,
+        "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": 0,
+        "audio.noise": false,
+        "audio.envelope": false,
+        "audio.filter": false,
+        "audio.pcm": false,
+        "audio.volume": false,
+        "audio.entropy": false,
+        "input.keyboard": true,
+        "input.joysticks": 0,
+        "input.pads": 0,
+        "input.mouse": false,
+        "input.paddles": false,
+        "storage.save": false,
+        "memory.ram": 57344,
+        "memory.banked": false,
+        "memory.bankedKib": 0,
+        "storage.kib": 0
+      },
+      "options": {},
+      "presets": {}
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.8bs

@@ -0,0 +1,42 @@
+// @8bitscript/web — browser target support for 8BitScript: the "hardware"
+// underneath.
+//
+// The module entry point named by the "8bitscript".entry field in this
+// package's package.json, resolved and linked for:
+//
+//     import { WebRegisters } from "@8bitscript/web";
+//
+// 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.
+//
+// There is no $900F or $D020 here: the web target has no fixed hardware, so
+// "the screen" is a canvas the host paints from wasm's own linear memory
+// (the `--initialMemory 1` page every web build reserves, per
+// @8bitscript/backend-web). This package's hardware surface is therefore an
+// AGREEMENT rather than a register map: a handful of fixed byte offsets in
+// that memory — two for the border and background colours, a virtual
+// character screen for everything `text` pokes, and one byte of input the
+// page writes and `@8bitscript/web/input` reads — which the host
+// (packages/cli's browser runtime, packages/cli/src/web-runtime.mjs) paints
+// from once per display refresh. It is the same deferred-apply contract a
+// VIC-II register has, aimed at a buffer instead.
+//
+// The character screen is 1000 cells, 40 wide — the C64's own screen shape
+// (see @8bitscript/c64) — picked as a safe superset of the VIC-20's smaller
+// 506-cell one so the same program's cell numbers never run off the end of
+// this buffer either. Two side-by-side regions, not interleaved, so a
+// caller that only ever touches a handful of cells leaves most of both
+// untouched.
+export namespace WebRegisters {
+    const BORDER_OFFSET: usmallint = 0;
+    const BACKGROUND_OFFSET: usmallint = 1;
+    const CHAR_BASE: usmallint = 2;
+    const COLOR_BASE: usmallint = 1002;
+    // Directions, confirm and cancel as the same Edge bits every input
+    // layer uses. The page writes this; poll() in ./input.8bs reads it.
+    // First byte after the 1000 colour cells at COLOR_BASE.
+    const INPUT_OFFSET: usmallint = 2002;
+}

package/src/input.8bs

@@ -0,0 +1,100 @@
+// @8bitscript/web/input — the browser runtime behind @8bitscript/input.
+//
+// Named by "8bitscript".exports["./input"] in this package's package.json,
+// and by "8bitscript".entry.web in @8bitscript/input's, so a portable
+// program writes
+//
+//     import { input } from "@8bitscript/input";
+//
+// and gets this file in a browser.
+//
+// ---- the page writes, the program reads ----------------------------------
+//
+// The program runs in a worker and cannot see DOM events. The page listens
+// for keys and stores a snapshot at WebRegisters.INPUT_OFFSET in the
+// shared wasm memory; poll() reads that byte once a frame, the same shape
+// every other machine's layer uses — a held mask, last frame's mask, and
+// the bits that began this frame. No new wasm import: the agreement page
+// is the port.
+//
+//   - **left / right / up / down** — ArrowLeft / ArrowRight / ArrowUp /
+//     ArrowDown.
+//   - **confirm** — Enter.
+//   - **cancel** — Escape.
+//
+// There is still no pointer. `pointer()` is a constant false; a mouse
+// belongs in the same snapshot when someone writes it, and
+// `input.mouse` stays false until then.
+//
+// ---- edges, not levels ---------------------------------------------------
+//
+// Every answer is **edge-triggered**: true on the one frame the press
+// begins, false while it is held. `poll()` must be called exactly once a
+// frame, right after waitFrame().
+import { WebRegisters } from "./index.8bs";
+
+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: the page owns the snapshot byte. Here so a
+    // program written for nine machines calls the same thing on all of
+    // them.
+    function begin(): void {
+    }
+
+    // Read the page's snapshot and work out what began this frame. Once
+    // a frame, right after waitFrame().
+    function poll(): void {
+        before = held;
+        held = memory.read(WebRegisters.INPUT_OFFSET);
+        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/pointer.8bs

@@ -0,0 +1,42 @@
+// @8bitscript/web/pointer — the web runtime behind @8bitscript/pointer,
+// and the one target where the pointer the user already has is the
+// problem rather than the solution.
+//
+// Every call here does nothing and `DRAWS` is false: the runtime now
+// delivers arrow keys through @8bitscript/web/input, but still no pointer.
+// A mouse belongs in the same shared snapshot as those keys, and until
+// that lands there is nothing to draw.
+//
+// This target has a decision the other eight do not, and it is worth
+// writing down before anyone implements it: **the user is already looking
+// at a real mouse cursor** — the browser's — sitting over the canvas. So
+// "draw a pointer" here means one of two quite different things. Either
+// the runtime hides the browser's cursor over the canvas and draws the
+// machine's own arrow, which is what makes a web build look like the
+// machine it is emulating and what every other target does; or it leaves
+// the browser's cursor alone and `DRAWS` stays false forever, with
+// `input.pointerCell()` reporting where that cursor is. The second is less
+// work and the first is more honest to what this target is for, and every
+// "hardware" fact of this machine is a decision recorded in the runtime's
+// source (see packages/web/AGENTS.md), so this one belongs written down
+// there when it is made.
+//
+// It costs the target nothing today: `DRAWS` is a const and every function
+// is empty, so a program's `if (pointer.DRAWS)` folds away and the backend
+// drops 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,107 @@
+// @8bitscript/web/screen — the browser target'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 web: @8bitscript/screen's entry is
+// keyed by machine and delegates here. Built on the memory-layout agreement
+// @8bitscript/web 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 — or, here, the host.
+import { WebRegisters } from "./index.8bs";
+
+// ---- the screen: border and background --------------------------------------
+//
+// Sixteen colours, masked the way the C64's registers are: the web target
+// has no palette size of its own to be faithful to, so it borrows the C64's
+// (see COLORS in packages/cli/src/web-runtime.mjs), which keeps colour
+// numbers meaning the same thing across every 8BitScript example. The host
+// reads the two bytes once per painted frame, so the picture changes at
+// the next paint.
+export namespace screen {
+    function setColors(border: u8, background: u8): void {
+        memory.write(WebRegisters.BORDER_OFFSET, border & 15);
+        memory.write(WebRegisters.BACKGROUND_OFFSET, background & 15);
+    }
+
+    // `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 < 1000; cell++) {
+            memory.write(WebRegisters.CHAR_BASE + cell, 32);
+        }
+    }
+
+    function setBackground(background: u8): void {
+        memory.write(WebRegisters.BACKGROUND_OFFSET, background & 15);
+    }
+
+    function setBorder(border: u8): void {
+        memory.write(WebRegisters.BORDER_OFFSET, border & 15);
+    }
+}
+
+// ---- colour names ----------------------------------------------------------
+//
+// The same eight names every machine's screen.8bs exports — Black, White,
+// Red, Cyan, Purple, Green, Blue, Yellow — so a program can write
+// `screen.setColors(BorderColor.BLUE, BackgroundColor.BLACK)` through
+// @8bitscript/screen and get blue on every target. The values are the C64's
+// sixteen colours in the C64's numbering, the palette this target borrows
+// (see setColors above).
+
+export namespace BorderColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}
+
+export namespace BackgroundColor {
+    const BLACK: utinyint = 0;
+    const WHITE: utinyint = 1;
+    const RED: utinyint = 2;
+    const CYAN: utinyint = 3;
+    const PURPLE: utinyint = 4;
+    const GREEN: utinyint = 5;
+    const BLUE: utinyint = 6;
+    const YELLOW: utinyint = 7;
+    const ORANGE: utinyint = 8;
+    const BROWN: utinyint = 9;
+    const LIGHT_RED: utinyint = 10;
+    const DARK_GREY: utinyint = 11;
+    const GREY: utinyint = 12;
+    const LIGHT_GREEN: utinyint = 13;
+    const LIGHT_BLUE: utinyint = 14;
+    const LIGHT_GREY: utinyint = 15;
+    // Not a colour: `blank(KEEP, ...)` leaves this one as it is. 255 is
+    // a value no register here takes.
+    const KEEP: utinyint = 255;
+}

package/src/text.8bs

@@ -0,0 +1,105 @@
+// @8bitscript/web/text — the browser target'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 web. Built on the memory-layout
+// agreement @8bitscript/web 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 written against
+// it doesn't know or care that "screen memory" is a real 6502 address on
+// most targets and a wasm-memory offset on this one.
+import { WebRegisters } from "./index.8bs";
+
+// Codes are ASCII, as they are everywhere (space, '0'-'9', 'A'-'Z' and a
+// little punctuation, upper case only); this buffer holds them as they
+// come, and the host (packages/cli/src/web-runtime.mjs) draws whatever
+// isn't blank as the text it is, once per painted frame — there is no
+// character ROM here to need screen codes for.
+// ---- 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.
+// `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 rides in bit 7 of the colour byte: the host fills the cell with
+// the foreground colour and punches the glyph out in the screen background.
+// A reverse space is a solid block. The low four bits stay the colour.
+function colorByte(): utinyint {
+    if (currentReverse) {
+        return currentColor + 128;
+    }
+    return currentColor;
+}
+
+function place(cell: usmallint, code: utinyint): void {
+    memory.write(WebRegisters.CHAR_BASE + cell, code);
+    memory.write(WebRegisters.COLOR_BASE + cell, colorByte());
+}
+
+export namespace text {
+    const CELL_COUNT: usmallint = 1000; // 40 columns x 25 rows
+    const COLUMNS: utinyint = 40; // cells per row, so cell = y * text.COLUMNS + x
+
+    function putChar(cell: usmallint, code: utinyint): void {
+        memory.write(WebRegisters.CHAR_BASE + cell, code);
+    }
+
+    function putColor(cell: usmallint, color: utinyint): void {
+        memory.write(WebRegisters.COLOR_BASE + cell, color);
+    }
+
+    function setColor(color: utinyint): void {
+        currentColor = color;
+    }
+
+    function setReverse(on: bool): void {
+        currentReverse = on;
+    }
+
+    function print(cell: usmallint, s: string): void {
+        for (let i: utinyint = 0; i < s.length; i++) {
+            place(cell + i, s[i]);
+        }
+    }
+
+    // Least significant digit first, from the right-hand end of the field.
+    // Division, unlike on the 6502 machines: wasm has a divide instruction,
+    // and the subtraction they use to avoid one is more code here.
+    function printNumber(cell: usmallint, value: usmallint, width: utinyint): void {
+        for (let i: utinyint = width; i > 0; i--) {
+            place(cell + i - 1, 48 + value % 10); // 48 = '0'
+            value = value / 10;
+        }
+    }
+}
+
+// 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;
+}