c64bridge 0.5.1 → 0.6.0

package/README.md

@@ -332,10 +332,16 @@ Please note that all logs use `stderr` since `stdout` is reserved for the MCP pr
 
 ## Build & Test 🧪
 
-- `npm run build` — type-check the TypeScript sources, normalize the dist layout for packaging, and regenerate the MCP API tables in `README.md`.
+- `bun install` — install dependencies for development (fast path). Node users can continue to use `npm install`.
+- `bun run build` — type-check the TypeScript sources, normalize the dist layout for packaging, and regenerate the MCP API tables in `README.md`.
 - `npm test` — run the integration tests against an in-process mock that emulates the c64 REST API.
 - `npm test -- --real` — exercise the same tests against a real c64 device. The runner reuses your MCP config (`~/.c64bridge.json` or `C64BRIDGE_CONFIG`) to determine the REST endpoint. You can also override explicitly with `--base-url=http://<host>`.
 - `npm run check` — convenience command that runs both the type-check and the mock-backed test suite.
+- `npm run coverage` — runs the Bun-powered test harness with coverage enabled and emits `coverage/lcov.info` (CI uploads to Codecov).
+
+**Development Tooling**
+
+This project uses [Bun](https://bun.sh/) for building and testing due to its high performance (significantly faster than npm/node for development workflows). The npm package remains fully compatible with Node.js 18+ and can be installed and run using standard npm commands. For release preparation, npm/node is still used to ensure everything works correctly on the target platform.
 
 The test runner accepts the following options:
 
@@ -347,6 +353,8 @@ The test runner accepts the following options:
 
 <!-- AUTO-GENERATED:MCP-DOCS-START -->
 
+This MCP server exposes **74 tools**, **25 resources**, and **7 prompts** for controlling your Commodore 64.
+
 ### Tools
 
 #### Programs
@@ -395,10 +403,10 @@ The test runner accepts the following options:
 | `analyze_audio` | Automatically analyze SID playback when the user requests verification feedback. | `sid`, `audio`, `analysis` |
 | `modplay_file` | Play a MOD tracker module stored on the Ultimate filesystem. | `sid`, `audio`, `playback` |
 | `music_compile_and_play` | Compile a SIDWAVE composition to PRG or SID and optionally play it immediately. | `sid`, `audio`, `music`, `compiler` |
-| `music_generate` | Generate a lightweight arpeggio and schedule playback on SID voice 1. | `sid`, `audio`, `music`, `generator` |
+| `music_generate` | Generate a lightweight arpeggio and schedule playback on SID voice 1. | `sid`, `audio`, `music`, `generator`, `pal-ntsc` |
 | `record_and_analyze_audio` | Record audio from the default input device and analyze SID playback characteristics. | `sid`, `audio`, `analysis` |
 | `sid_note_off` | Release a SID voice by clearing its GATE bit. | `sid`, `audio`, `control`, `music` |
-| `sid_note_on` | Trigger a SID voice with configurable waveform, pulse width, and ADSR envelope. See c64://specs/sid. | `sid`, `audio`, `control`, `music` |
+| `sid_note_on` | Trigger a SID voice with configurable waveform, pulse width, and ADSR envelope. See c64://specs/sid. | `sid`, `audio`, `control`, `music`, `pal-ntsc` |
 | `sid_reset` | Reset the SID chip either softly (silence) or with a full register scrub. | `sid`, `audio`, `control` |
 | `sid_silence_all` | Silence all SID voices by clearing control and envelope registers. | `sid`, `audio`, `control` |
 | `sid_volume` | Set the SID master volume register at $D418. See c64://specs/sid. | `sid`, `audio`, `control` |
@@ -458,8 +466,8 @@ The test runner accepts the following options:
 
 | Name | Description | Tags |
 | --- | --- | --- |
-| `create_petscii_image` | Create PETSCII art from prompts or text, optionally run it on the C64, and return metadata. See c64://specs/basic and c64://specs/vic. | `graphics`, `vic`, `petscii`, `basic` |
-| `generate_sprite_prg` | Generate and execute a PRG that displays a sprite from raw 63-byte data. See c64://specs/vic for registers. | `graphics`, `vic`, `sprite`, `assembly` |
+| `create_petscii_image` | Create PETSCII art from prompts or text, optionally run it on the C64, and return metadata including PETSCII codes and glyphs. See c64://specs/basic, c64://specs/vic, and c64://specs/charset. | `graphics`, `vic`, `petscii`, `basic`, `pal-ntsc` |
+| `generate_sprite_prg` | Generate and execute a PRG that displays a sprite from raw 63-byte data. See c64://specs/vic for registers. | `graphics`, `vic`, `sprite`, `assembly`, `pal-ntsc` |
 | `render_petscii_screen` | Render PETSCII text to the screen with optional border/background colours. See c64://specs/basic. | `graphics`, `vic`, `basic`, `screen` |
 
 #### Printer
@@ -561,12 +569,16 @@ The test runner accepts the following options:
 | `c64://docs/index` | Explains how to approach each knowledge bundle and when to consult it. |
 | `c64://context/bootstrap` | Step-by-step rules for safe automation, verification, and rollback on the C64. |
 | `c64://specs/basic` | Token definitions, syntax rules, and device I/O guidance for BASIC v2. |
+| `c64://docs/basic/pitfalls` | Quickref covering quotation handling, line length, tokenization, variable names, and other BASIC traps. |
 | `c64://specs/assembly` | Official opcode matrix, addressing modes, and zero-page strategy for the 6510 CPU. |
 | `c64://specs/sid` | Register map, waveform behaviour, and ADSR envelopes for expressive SID playback. |
 | `c64://specs/sidwave` | Defines the SIDWAVE interchange format used by the SID composer workflow. |
 | `c64://docs/sid/file-structure` | Explains PSID/RSID headers, metadata blocks, and compatibility notes for imported music. |
 | `c64://docs/sid/best-practices` | Captures proven waveforms, ADSR presets, phrasing, and verification workflow for pleasant SID music. |
 | `c64://specs/vic` | Covers raster timing, sprite control, colour RAM, and bitmap modes on the VIC-II. |
+| `c64://specs/charset` | Character code table mapping PETSCII codes to screen codes, glyphs, and keyboard input. |
+| `c64://docs/petscii-style` | Documents colour palette, readability presets, dithering patterns, and best practices for creating artistic and readable PETSCII displays. |
+| `c64://docs/sprite-charset-workflows` | Documents sprite and charset workflows, memory layout, VIC-II configuration, common pitfalls, and proven techniques for hardware-accelerated graphics. |
 | `c64://specs/memory-map` | Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions. |
 | `c64://specs/memory-low` | Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses. |
 | `c64://specs/memory-kernal` | Lists KERNAL ROM vectors and service routines for OS-level functionality. |

package/data/assembly/assembly-spec.md

@@ -194,3 +194,27 @@ Modes (columns): `A  #  ZP ZPX ZPY ABS ABSX ABSY IND IZX IZY REL IMP`
 - Data: `.byte expr[,…]`, `.word expr[,…]`  
 - Symbols: `name = expr` / `.equ name, expr`  
 - Alignment/fill (assembler‑specific): `.align n`, `.fill count, value`
+
+## Tips and Tricks
+
+### Basic Start Header
+
+- PRG file = 2-byte little-endian load address + bytes
+- Place a tokenized BASIC line at $0801, e.g. `10 SYS 4096` (token SYS = $9E) to jump to $1000
+- Ensure load-address at PRG start matches where BASIC was placed (e.g. $01 $08)
+- Machine code may live at $1000 or directly after BASIC; adjust SYS target accordingly
+
+### Display Text on Screen
+
+1) KERNAL CHROUT (portable)
+   - Put PETSCII byte in A; JSR $FFD2 to print at cursor. Handles charset mapping.
+   - Use for portability and when charset may vary.
+2) Direct screen writes (fast)
+   - STA $0400,X writes VIC-II screen codes directly. Use when you control charset and need speed.
+   - Color via STA $D800,X (4-bit color index).
+
+Screen-code conversion
+
+- If input is ASCII uppercase 'A'..'Z', convert: screen = PETSCII - $40 (e.g. $41→$01). Implement in a small loop if needed.
+
+This file is intentionally minimal: use `basicConverter` / `assemblyConverter` in `src/` for tokenization/PRG building and `data/video/character-set.csv` for exact screen-code mappings.

package/data/assembly/examples/video/hello_world.asm

@@ -0,0 +1,39 @@
+; hello_world_prg.asm
+; Single-file PRG layout:
+; - Tokenized one-line BASIC at $0801: 10 SYS 4096
+; - Machine code placed at $1000 which writes the message directly to screen RAM ($0400)
+;   (no KERNAL CHROUT or BASIC printing is used)
+
+        .org $0801
+        ; next-line pointer (little-endian) -> $080C (start + line length)
+        .byte $0C, $08
+        ; line number 10
+        .byte $0A, $00
+        ; tokenized content: SYS (0x9E), space (0x20), '4','0','9','6' (ASCII/PETSCII digits)
+        .byte $9E, $20, $34, $30, $39, $36
+        ; line terminator
+        .byte $00
+        ; program end marker (two zero bytes)
+        .byte $00, $00
+
+        ; -- machine code at $1000 ------------------------------------------------
+        .org $1000
+start:
+        ldx #$00            ; X = 0
+write_loop:
+        lda message, x      ; load byte from message
+        beq done            ; zero terminator -> finished
+        sta $0400, x        ; write character to screen RAM (fast direct write)
+        inx
+        jmp write_loop
+
+done:
+        rts
+
+message:
+        ; ASCII bytes for: HELLO, WORLD!  (0-terminated)
+        ; VIC-II screen codes for: HELLO, WORLD! (screen codes from data/video/character-set.csv)
+        ; H E  L  L  O   ,    <space> W  O  R  L  D  !
+        .byte $08, $05, $0C, $0C, $0F, $2C, $20, $17, $0F, $12, $0C, $04, $21, $00
+
+        ; End of file

package/data/basic/basic-pitfalls.md

@@ -0,0 +1,236 @@
+# BASIC Pitfalls Quickref
+
+Common mistakes and gotchas when writing Commodore BASIC v2 programs.
+
+## Quotation Handling
+
+**Problem:** Strings with unmatched quotes cause parsing errors.
+
+```basic
+10 PRINT "HELLO WORLD
+```
+
+**Solution:** Always close string literals with matching double quotes.
+
+```basic
+10 PRINT "HELLO WORLD"
+```
+
+**Escaping quotes:** BASIC v2 has no escape sequence. Use `CHR$(34)` for embedded quotes.
+
+```basic
+10 PRINT "HE SAID " + CHR$(34) + "HELLO" + CHR$(34)
+```
+
+## Line Length Limits
+
+**Problem:** BASIC lines are limited to 80 characters (2 physical screen lines). Longer lines are truncated or cause errors.
+
+**Solution:** Break long statements across multiple numbered lines.
+
+```basic
+10 A=1:B=2:C=3
+20 D=A+B+C
+```
+
+**Multi-statement lines:** Use `:` to separate statements, but watch total character count.
+
+## Line Numbers
+
+**Problem:** Line numbers must be 0-63999. Reordering requires renumbering.
+
+**Best practice:** Use increments of 10 (e.g., 10, 20, 30) to leave room for insertions.
+
+```basic
+10 REM MAIN LOOP
+20 FOR I=1 TO 10
+30 PRINT I
+40 NEXT I
+```
+
+## Tokenization Issues
+
+**Problem:** BASIC tokenizes keywords, which affects string matching and `DATA` statements.
+
+**Impact on DATA:**
+
+```basic
+10 DATA PRINT,GOTO,END
+20 READ A$,B$,C$
+30 PRINT A$  :REM DISPLAYS "P" + token bytes, not "PRINT"
+```
+
+**Solution:** Quote `DATA` strings that might contain keywords.
+
+```basic
+10 DATA "PRINT","GOTO","END"
+```
+
+## Variable Names
+
+**Problem:** Only the first two characters are significant. `SPEED` and `SPECIAL` both resolve to `SP`.
+
+```basic
+10 SPEED=10
+20 SPECIAL=20
+30 PRINT SPEED  :REM PRINTS 20, NOT 10
+```
+
+**Solution:** Use unique first-two-character combinations.
+
+```basic
+10 SP=10
+20 SZ=20
+```
+
+## Array Dimensions
+
+**Problem:** Arrays default to dimension 10 (indices 0-10, 11 elements). Using `DIM A(10)` also creates 11 elements (0-10).
+
+**Solution:** Explicitly dimension arrays to the exact size needed and remember the 0 index.
+
+```basic
+10 DIM A(9)  :REM CREATES 10 ELEMENTS (0-9)
+20 FOR I=0 TO 9
+30 A(I)=I*2
+40 NEXT I
+```
+
+## String Concatenation
+
+**Problem:** String concatenation without spaces can be ambiguous.
+
+```basic
+10 A$="HELLO"
+20 B$="WORLD"
+30 C$=A$+B$  :REM WORKS
+40 D$=A$B$   :REM SYNTAX ERROR
+```
+
+**Solution:** Always use `+` for concatenation.
+
+## Floating Point Precision
+
+**Problem:** BASIC uses 5-byte floating point with limited precision (~9 digits). Rounding errors accumulate.
+
+```basic
+10 A=0.1+0.1+0.1
+20 PRINT A=0.3  :REM MAY PRINT 0 (FALSE)
+```
+
+**Solution:** Use integer arithmetic when exact values are required, or add small epsilon for comparisons.
+
+```basic
+10 A=1+1+1
+20 B=A/10
+30 IF ABS(B-0.3)<0.0001 THEN PRINT "CLOSE ENOUGH"
+```
+
+## Device Numbers
+
+**Problem:** Using wrong device numbers causes `FILE NOT FOUND` or hangs.
+
+- Device 0: Keyboard
+- Device 1: Cassette
+- Device 3: Screen
+- Device 4-7: Printers
+- Device 8-11: Disk drives
+
+**Solution:** Always verify device numbers before `OPEN` statements.
+
+```basic
+10 OPEN 1,8,15,"I0":REM OPEN COMMAND CHANNEL ON DRIVE 8
+```
+
+## Memory Conflicts
+
+**Problem:** BASIC program area grows downward from `$0801`. String/array space grows upward from `$9FFF` (or lower if adjusted). They can collide.
+
+**Symptoms:** `OUT OF MEMORY` errors or system crashes.
+
+**Solution:** Monitor free memory with `FRE(0)` and keep programs compact.
+
+```basic
+10 PRINT FRE(0)  :REM PRINT FREE BYTES
+```
+
+## GOTO/GOSUB Loops
+
+**Problem:** Excessive `GOSUB` without matching `RETURN` exhausts the stack (limited to ~50 nested calls).
+
+**Solution:** Structure programs with main loops and balanced subroutine calls.
+
+```basic
+10 FOR I=1 TO 10
+20 GOSUB 100
+30 NEXT I
+40 END
+100 PRINT I
+110 RETURN
+```
+
+## Timing and Speed
+
+**Problem:** BASIC is interpreted and slow (~1000 statements/sec). Tight loops with many operations lag.
+
+**Solution:** Optimize hot loops, minimize array access, and consider assembly for performance-critical code.
+
+```basic
+10 REM SLOW
+20 FOR I=1 TO 1000
+30 A=A+1:B=B+1:C=C+1
+40 NEXT I
+
+10 REM FASTER
+20 FOR I=1 TO 1000
+30 A=A+1
+40 NEXT I:B=A:C=A
+```
+
+## Input Quirks
+
+**Problem:** `INPUT` statements can be aborted with `STOP` or `RUN/STOP-RESTORE`, leaving variables unchanged or partially set.
+
+**Solution:** Validate inputs and handle empty/invalid responses.
+
+```basic
+10 INPUT "ENTER NUMBER";A
+20 IF A<1 OR A>100 THEN PRINT "INVALID":GOTO 10
+```
+
+## Screen Codes vs. PETSCII
+
+**Problem:** `PRINT` uses PETSCII codes, but `POKE` to screen memory requires screen codes (different mappings).
+
+**Solution:** Use conversion routines or lookup tables when directly writing to screen RAM ($0400-$07E7).
+
+```basic
+10 REM PRINT USES PETSCII
+20 PRINT "A"  :REM DISPLAYS 'A'
+
+30 REM POKE TO SCREEN USES SCREEN CODES
+40 POKE 1024,1  :REM DISPLAYS 'A' (SCREEN CODE 1)
+```
+
+## RESTORE Statement
+
+**Problem:** `RESTORE` without line number resets `READ` pointer to the first `DATA` statement. If you need to re-read from a specific line, use `RESTORE linenum`.
+
+```basic
+10 DATA 1,2,3
+20 DATA 4,5,6
+30 READ A:READ B:READ C
+40 RESTORE 20  :REM RESET TO LINE 20
+50 READ D:READ E:READ F
+```
+
+## Summary
+
+- **Always close quotes** and watch line lengths (80 chars).
+- **Use unique variable prefixes** (first 2 chars matter).
+- **Dimension arrays explicitly** and remember 0-indexing.
+- **Quote DATA strings** to avoid tokenization issues.
+- **Check device numbers** before OPEN.
+- **Balance GOSUB/RETURN** to avoid stack overflow.
+- **Validate INPUT** to handle user errors gracefully.
+- **Convert between PETSCII and screen codes** when needed.