c64bridge 1.0.4 → 1.0.6

package/dist/tools/translation/basicTokenizer.js

@@ -9,13 +9,18 @@ import { Buffer } from "node:buffer";
 import { asciiToPetscii, encodeStringWithNames } from "../../petscii.js";
 const DEFAULT_START_ADDRESS = 0x0801;
 const REM_TOKEN = 0x8f;
+const DATA_TOKEN = 0x83;
+const PRINT_TOKEN = 0x99;
+// Highest line number the BASIC V2 line parser (LINGET) accepts; larger values give ?SYNTAX ERROR.
+const MAX_LINE_NUMBER = 63999;
 const TOKEN_TABLE = buildTokenTable();
 export function basicToPrg(source, options) {
     const startAddress = options?.startAddress ?? DEFAULT_START_ADDRESS;
     const normalizedSource = normalize(source);
     const lines = normalizedSource.split("\n");
-    const lineBuffers = [];
-    let currentAddress = startAddress;
+    // Like typing lines into the C64, lines are kept in ascending order, a later
+    // duplicate replaces the earlier line, and a bare line number deletes it.
+    const programLines = new Map();
     for (const rawLine of lines) {
         const trimmedRight = rawLine.replace(/\s+$/u, "");
         if (trimmedRight === "") {
@@ -26,11 +31,20 @@ export function basicToPrg(source, options) {
             throw new Error(`Expected line number at: "${rawLine}"`);
         }
         const lineNumber = Number.parseInt(match[1], 10);
-        if (!Number.isInteger(lineNumber) || lineNumber < 0 || lineNumber > 65535) {
-            throw new Error(`Line number out of range: ${match[1]}`);
+        if (!Number.isInteger(lineNumber) || lineNumber < 0 || lineNumber > MAX_LINE_NUMBER) {
+            throw new Error(`Line number out of range: ${match[1]} (C64 BASIC accepts 0-${MAX_LINE_NUMBER})`);
         }
         const content = match[2] ?? "";
-        const tokenised = tokenize(content);
+        if (content === "") {
+            programLines.delete(lineNumber);
+            continue;
+        }
+        programLines.set(lineNumber, tokenize(content));
+    }
+    const lineBuffers = [];
+    let currentAddress = startAddress;
+    for (const lineNumber of [...programLines.keys()].sort((a, b) => a - b)) {
+        const tokenised = programLines.get(lineNumber);
         const lineLength = 2 + 2 + tokenised.length + 1;
         const nextAddress = currentAddress + lineLength;
         const lineBuffer = Buffer.alloc(lineLength);
@@ -56,8 +70,16 @@ function tokenize(content) {
     let index = 0;
     let inString = false;
     let inRemark = false;
+    // As in the ROM CRUNCH routine, DATA items are copied literally until the
+    // next ':' outside quotes, and '?' outside strings, REM, and DATA becomes PRINT.
+    let inData = false;
     while (index < content.length) {
-        if (!inString && !inRemark) {
+        if (!inString && !inRemark && !inData) {
+            if (upper[index] === "?") {
+                bytes.push(PRINT_TOKEN);
+                index += 1;
+                continue;
+            }
             const token = matchToken(upper, index);
             if (token) {
                 bytes.push(token.byte);
@@ -65,6 +87,9 @@ function tokenize(content) {
                 if (token.byte === REM_TOKEN) {
                     inRemark = true;
                 }
+                else if (token.byte === DATA_TOKEN) {
+                    inData = true;
+                }
                 continue;
             }
         }
@@ -82,15 +107,24 @@ function tokenize(content) {
                     end += 1;
                 }
                 const segment = content.slice(start, end);
-                const encoded = encodeStringWithNames(segment);
+                // Lowercase letters would print as graphics characters in the default
+                // character set, so string text is stored as the PETSCII letters.
+                const encoded = encodeStringWithNames(segment, { foldLowercase: true });
                 for (const b of encoded)
                     bytes.push(b);
                 index = end; // leave closing quote to be processed next iteration
             }
             continue;
         }
-        const plainChar = (!inString && !inRemark ? upper[index] : char) ?? char;
+        // REM text folds only ASCII a-z, like string text (LIST would show them as
+        // graphics); full Unicode upper-casing could change length or leave Latin-1.
+        const plainChar = inRemark
+            ? (char >= "a" && char <= "z" ? char.toUpperCase() : char)
+            : (!inString ? upper[index] : char) ?? char;
         bytes.push(asciiToPetscii(plainChar));
+        if (inData && !inString && plainChar === ":") {
+            inData = false;
+        }
         index += 1;
     }
     if (bytes.length === 0) {
@@ -112,7 +146,7 @@ function buildTokenTable() {
         ["END", 0x80],
         ["FOR", 0x81],
         ["NEXT", 0x82],
-        ["DATA", 0x83],
+        ["DATA", DATA_TOKEN],
         ["INPUT#", 0x84],
         ["INPUT", 0x85],
         ["DIM", 0x86],
@@ -134,7 +168,7 @@ function buildTokenTable() {
         ["DEF", 0x96],
         ["POKE", 0x97],
         ["PRINT#", 0x98],
-        ["PRINT", 0x99],
+        ["PRINT", PRINT_TOKEN],
         ["CONT", 0x9a],
         ["LIST", 0x9b],
         ["CLR", 0x9c],

package/dist/tools/translation/opcodeInventory.js

@@ -55,7 +55,7 @@ const OPCODE_ROWS = [
     // 0xE0-0xEF
     [["CPX", M.Imm], ["SBC", M.IndX], ["NOP", M.Imm], ["INS", M.IndX], ["CPX", M.Zp], ["SBC", M.Zp], ["INC", M.Zp], ["INS", M.Zp], ["INX", M.Imp], ["SBC", M.Imm], ["NOP", M.Imp], ["SBC", M.Imm], ["CPX", M.Abs], ["SBC", M.Abs], ["INC", M.Abs], ["INS", M.Abs]],
     // 0xF0-0xFF
-    [["BEQ", M.Rel], ["SBC", M.IndY], ["HLT", M.Imp], ["INS", M.IndY], ["NOP", M.ZpS], ["SBC", M.ZpX], ["INC", M.ZpX], ["INS", M.ZpX], ["SED", M.Imp], ["SBC", M.AbsY], ["NOP", M.Imp], ["INS", M.AbsY], ["NOP", M.AbsX], ["SBC", M.AbsX], ["INC", M.AbsX], ["INS", M.AbsX]],
+    [["BEQ", M.Rel], ["SBC", M.IndY], ["HLT", M.Imp], ["INS", M.IndY], ["NOP", M.ZpX], ["SBC", M.ZpX], ["INC", M.ZpX], ["INS", M.ZpX], ["SED", M.Imp], ["SBC", M.AbsY], ["NOP", M.Imp], ["INS", M.AbsY], ["NOP", M.AbsX], ["SBC", M.AbsX], ["INC", M.AbsX], ["INS", M.AbsX]],
 ];
 const ILLEGAL_MAP = [
     0x989C, 0x9C9C, 0x888C, 0x9C9C,

package/dist/tools/types.js

@@ -104,7 +104,8 @@ export function createOperationDispatcher(toolName, handlers) {
             throw new ToolValidationError(`${toolName} is a grouped tool and requires an ${OPERATION_DISCRIMINATOR} string to select an operation`, { path: `$.${OPERATION_DISCRIMINATOR}`, details: { allowed } });
         }
         const opKey = opValue;
-        const handler = handlers[opKey];
+        // Own properties only: "constructor", "toString", etc. must not resolve to Object.prototype members.
+        const handler = hasOwnKey(handlers, opKey) ? handlers[opKey] : undefined;
         if (!handler) {
             throw new ToolValidationError(`${toolName} does not support ${OPERATION_DISCRIMINATOR} "${opValue}"`, { path: `$.${OPERATION_DISCRIMINATOR}`, details: { allowed } });
         }
@@ -184,7 +185,7 @@ function resolveSupportedPlatforms(tool, args, defaultPlatforms) {
     if (!operation) {
         return basePlatforms;
     }
-    const operationPlatforms = tool.operationPlatforms?.[operation];
+    const operationPlatforms = ownValue(tool.operationPlatforms, operation);
     return operationPlatforms && operationPlatforms.length > 0 ? operationPlatforms : basePlatforms;
 }
 function resolveUnsupportedToolName(toolName, tool, args) {
@@ -192,11 +193,17 @@ function resolveUnsupportedToolName(toolName, tool, args) {
     if (!operation) {
         return toolName;
     }
-    const mappedName = tool.operationToolNames?.[operation];
+    const mappedName = ownValue(tool.operationToolNames, operation);
     if (mappedName) {
         return mappedName;
     }
-    return tool.operationPlatforms?.[operation] ? operation : toolName;
+    return ownValue(tool.operationPlatforms, operation) ? operation : toolName;
+}
+function hasOwnKey(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function ownValue(record, key) {
+    return record && hasOwnKey(record, key) ? record[key] : undefined;
 }
 function getSelectedOperation(args) {
     if (typeof args !== "object" || args === null) {

package/dist/tools/vice.js

@@ -33,7 +33,7 @@ const resourceValueSchema = {
     },
 };
 const resourceNameSchema = stringSchema({
-    description: "VICE resource name (example: SidEngine, C64Model).",
+    description: "VICE resource name (example: SidEngine, SidModel).",
     minLength: 1,
     maxLength: 64,
     pattern: RESOURCE_NAME_PATTERN,

package/dist/vicBitmap.js

@@ -4,6 +4,8 @@ const BITMAP_BYTE_LENGTH = 8000;
 const SCREEN_RAM_BYTE_LENGTH = 1000;
 const COLOR_RAM_BYTE_LENGTH = 1000;
 const COLOR_RAM_ADDRESS = 0xD800;
+const CHAR_ROM_SHADOW_OFFSET = 0x1000;
+const CHAR_ROM_SHADOW_LENGTH = 0x1000;
 const VIC_PALETTE = [
     [0x00, 0x00, 0x00],
     [0xFF, 0xFF, 0xFF],
@@ -83,6 +85,17 @@ export function resolveVicBitmapMemoryLayout(bitmapAddress = 0x2000, screenAddre
     if (rangesOverlap(bitmapAddress, BITMAP_BYTE_LENGTH, screenAddress, SCREEN_RAM_BYTE_LENGTH)) {
         throw new Error("Bitmap RAM and screen RAM must not overlap");
     }
+    // In banks 0 and 2 the VIC reads the character ROM, not RAM, at bank offsets $1000-$1FFF.
+    if (bank === 0 || bank === 2) {
+        const shadowStart = bankBase + CHAR_ROM_SHADOW_OFFSET;
+        const shadowRange = `$${formatHex(shadowStart)}-$${formatHex(shadowStart + CHAR_ROM_SHADOW_LENGTH - 1)}`;
+        if (rangesOverlap(bitmapOffset, BITMAP_BYTE_LENGTH, CHAR_ROM_SHADOW_OFFSET, CHAR_ROM_SHADOW_LENGTH)) {
+            throw new Error(`Bitmap RAM must not overlap the character ROM shadow at ${shadowRange} in VIC bank ${bank}`);
+        }
+        if (rangesOverlap(screenOffset, SCREEN_RAM_BYTE_LENGTH, CHAR_ROM_SHADOW_OFFSET, CHAR_ROM_SHADOW_LENGTH)) {
+            throw new Error(`Screen RAM must not overlap the character ROM shadow at ${shadowRange} in VIC bank ${bank}`);
+        }
+    }
     const screenNibble = ((screenOffset / 0x0400) & 0x0F) << 4;
     const bitmapBit = bitmapOffset === 0x2000 ? 0x08 : 0x00;
     return {
@@ -310,6 +323,9 @@ function validateAddress(address, length, label) {
         throw new Error(`${label} range must fit within 64 KB address space`);
     }
 }
+function formatHex(value) {
+    return value.toString(16).toUpperCase().padStart(4, "0");
+}
 function rangesOverlap(leftStart, leftLength, rightStart, rightLength) {
     const leftEnd = leftStart + leftLength - 1;
     const rightEnd = rightStart + rightLength - 1;

package/dist/vice/mockServer.js

@@ -40,10 +40,16 @@ export class ViceMockServer {
         this.registerMetadata = buildDefaultRegisterMetadata();
         this.registerValues = new Map();
         this.resources = new Map();
+        /** Output lines of VICE's I/O simulation joyport device per port (0 = port 1). */
+        this.joyportOutput = [0, 0];
         this.sockets = new Set();
+        /** Images attached with autostart, and drive CPU resets, as observed by tests. */
+        this.autostarts = [];
+        this.driveResets = [];
         this.host = options?.host ?? "127.0.0.1";
         this.requestedPort = options?.port;
         this.resetState();
+        this.resetResources();
     }
     async start() {
         if (this.server)
@@ -114,9 +120,26 @@ export class ViceMockServer {
         switch (cmd) {
             case 0x85: // info
                 return buildResponse(cmd, reqId);
-            case 0xCC: // reset
-                this.resetState();
+            case 0xCC: { // reset: types 8-11 reset only that drive's CPU
+                const type = body[0] ?? 0;
+                if (type >= 8 && type <= 11) {
+                    this.driveResets.push(type);
+                }
+                else {
+                    this.resetState();
+                }
+                return buildResponse(cmd, reqId);
+            }
+            case 0xDD: { // autostart: power-cycles, attaches the image to drive 8 and loads (run=1 also runs)
+                const nameLength = body[3] ?? 0;
+                this.autostarts.push({
+                    run: body[0] === 1,
+                    fileIndex: body.readUInt16LE(1),
+                    filename: body.subarray(4, 4 + nameLength).toString("utf8"),
+                });
+                this.renderAutoload(body[0] === 1);
                 return buildResponse(cmd, reqId);
+            }
             case 0x11: { // checkpoint get
                 const id = body.readUInt32LE(0);
                 const checkpoint = this.checkpoints.get(id);
@@ -185,13 +208,17 @@ export class ViceMockServer {
             case 0x01: { // mem get
                 const start = body.readUInt16LE(1);
                 const end = body.readUInt16LE(3);
-                const length = Math.max(0, end - start + 1);
+                if (start > end) {
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x81); // VICE rejects start > end with INVALID_PARAMETER.
+                }
+                const length = end - start + 1;
                 const payload = Buffer.alloc(2 + length);
-                payload.writeUInt16LE(length, 0);
+                payload.writeUInt16LE(length & 0xffff, 0); // Like VICE: a full 64 KB read reports ML = 0.
                 for (let i = 0; i < length; i += 1) {
                     payload[2 + i] = this.memory[(start + i) & 0xffff];
                 }
                 this.applyHeartbeatOverlay(start, length, payload);
+                this.applyJoyportOverlay(start, length, payload);
                 return buildResponse(cmd, reqId, payload);
             }
             case 0x02: { // mem set
@@ -246,7 +273,7 @@ export class ViceMockServer {
                 const name = body.subarray(1, 1 + nameLen).toString("utf8");
                 const value = this.resources.get(name);
                 if (value === undefined) {
-                    return buildResponse(cmd, reqId, Buffer.from([0, 0]));
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x01); // VICE: OBJECT_MISSING for an unknown resource.
                 }
                 if (typeof value === "number") {
                     const buffer = Buffer.alloc(2 + 4);
@@ -266,12 +293,20 @@ export class ViceMockServer {
                 const isNumber = body[0] === 1;
                 const nameLen = body[1] ?? 0;
                 const name = body.subarray(2, 2 + nameLen).toString("utf8");
+                if (!this.resources.has(name)) {
+                    // VICE: an unknown integer resource fails resources_set (CMD_FAILURE); an unknown string one is OBJECT_MISSING.
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), isNumber ? 0x8f : 0x01);
+                }
                 if (isNumber) {
                     const valueLen = body[2 + nameLen] ?? 0;
                     const valueBytes = body.subarray(3 + nameLen, 3 + nameLen + valueLen);
                     const padded = Buffer.alloc(4);
                     valueBytes.copy(padded, 0, 0, Math.min(4, valueBytes.length));
                     const value = padded.readInt32LE(0);
+                    // VICE rejects joyport device ids it does not have (JOYPORT_MAX_DEVICES is 44 in 3.10).
+                    if (/^JoyPort\dDevice$/.test(name) && (value < 0 || value >= 44)) {
+                        return buildResponse(cmd, reqId, Buffer.alloc(0), 0x8f);
+                    }
                     this.resources.set(name, value);
                 }
                 else {
@@ -281,6 +316,18 @@ export class ViceMockServer {
                 }
                 return buildResponse(cmd, reqId);
             }
+            case 0xA2: { // joyport set: like VICE, it only stores the I/O simulation device's output lines
+                const port = body.readUInt16LE(0);
+                const value = body.readUInt16LE(2);
+                if (port > 1) {
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x01);
+                }
+                if (value > 0xff) {
+                    return buildResponse(cmd, reqId, Buffer.alloc(0), 0x81);
+                }
+                this.joyportOutput[port] = value & 0x1f;
+                return buildResponse(cmd, reqId);
+            }
             case 0xAA: // exit monitor
                 return buildResponse(cmd, reqId);
             case 0xBB: // quit
@@ -359,7 +406,9 @@ export class ViceMockServer {
         return payload;
     }
     encodeDisplay() {
-        const pixels = Buffer.alloc(64, 0);
+        const pixels = Buffer.alloc(64);
+        for (let i = 0; i < pixels.length; i += 1)
+            pixels[i] = i & 0x0f;
         const header = Buffer.alloc(17);
         const pixelLength = Buffer.alloc(4);
         header.writeUInt32LE(13, 0);
@@ -371,7 +420,9 @@ export class ViceMockServer {
         header.writeUInt16LE(200, 14);
         header[16] = 8;
         pixelLength.writeUInt32LE(pixels.length, 0);
-        return Buffer.concat([header, pixelLength, pixels]);
+        // VICE 3.9/3.10 send a body of 4 + FL + BL bytes, which drops the last 4 pixel bytes.
+        const full = Buffer.concat([header, pixelLength, pixels]);
+        return full.subarray(0, 4 + 13 + pixels.length);
     }
     applyRegisterWrites(body) {
         if (body.length < 3) {
@@ -430,11 +481,51 @@ export class ViceMockServer {
         for (const meta of this.registerMetadata) {
             this.registerValues.set(meta.id, 0);
         }
+        this.joyportOutput = [0, 0];
+    }
+    // Resources survive a machine reset in VICE. Only resources that exist in
+    // VICE 3.10 are known; others fail the way VICE fails (see below).
+    resetResources() {
         this.resources = new Map([
-            ["C64Model", 2],
             ["SidEngine", 1],
+            ["JoyPort1Device", 1],
+            ["JoyPort2Device", 1],
+            ["Drive8Type", 1541],
+            ["Drive9Type", 0],
+            ["Drive10Type", 0],
+            ["Drive11Type", 0],
+            ["VICIIDoubleSize", 0],
+            ["VICIIBorderMode", 0],
+            ["VICIIFullscreen", 0],
+            ["SoundVolume", 100],
+            ["SidModel", 0],
+            ["MachineVideoStandard", 1],
+            ["KernalName", "kernal-901227-03.bin"],
         ]);
     }
+    /** Lines a joyport device drives, as CIA1 sees them (active low); only the I/O simulation device (37) is modelled. */
+    joyportLines(port) {
+        return this.resources.get(`JoyPort${port}Device`) === 37 ? this.joyportOutput[port - 1] : 0xff;
+    }
+    // CIA1 port A ($DC00) reads joyport 2 and port B ($DC01) joyport 1, ANDed with the keyboard lines.
+    applyJoyportOverlay(start, length, payload) {
+        for (const [address, port] of [[0xdc00, 2], [0xdc01, 1]]) {
+            if (address >= start && address < start + length) {
+                payload[2 + address - start] = 0xff & this.joyportLines(port);
+            }
+        }
+    }
+    // What VICE's autoload leaves on screen after its power cycle: the typed LOAD and READY.
+    renderAutoload(run) {
+        // The power cycle's KERNAL reset clears $0200-$03FF (RAMTAS).
+        this.memory.fill(0x00, 0x0200, 0x0400);
+        this.memory.fill(0x20, SCREEN_BASE, SCREEN_BASE + 1000);
+        const lines = ['LOAD"*",8,1', "", "SEARCHING FOR *", "LOADING", "READY.", ...(run ? ["RUN"] : [])];
+        lines.forEach((line, row) => {
+            const codes = asciiToScreenCodes(line);
+            codes.copy(Buffer.from(this.memory.buffer, SCREEN_BASE + row * 40, codes.length));
+        });
+    }
     renderHello() {
         if (this.helloReady)
             return;

package/dist/vice/readiness.js

@@ -126,15 +126,10 @@ export function asciiToScreenCodes(text) {
             out.push(ch.charCodeAt(0) - 64);
         else if (ch >= '0' && ch <= '9')
             out.push(0x30 + (ch.charCodeAt(0) - 48));
-        else if (ch === ' ')
-            out.push(0x20);
-        else if (ch === '.')
-            out.push(0x2E);
-        else if (ch === ':')
-            out.push(0x3A);
-        else if (ch === '-')
-            out.push(0x2D);
-        // extend as needed; ignore others
+        // Space, digits and punctuation ($20-$3F) have the same screen codes as ASCII.
+        else if (ch >= ' ' && ch <= '?')
+            out.push(ch.charCodeAt(0));
+        // ignore others
     }
     return Buffer.from(out);
 }

package/dist/vice/viceClient.js

@@ -159,6 +159,24 @@ export class ViceClient {
     async resetSoft() { await this.send(0xCC, Buffer.from([0x00])); }
     async resetHard() { await this.send(0xCC, Buffer.from([0x01])); }
     async reset(type = 0) { await this.send(0xCC, Buffer.from([type])); }
+    /** Reset only the drive CPU of unit 8-11 (BM 0xCC reset types 8-11). */
+    async resetDrive(unit) { await this.send(0xCC, Buffer.from([unit])); }
+    /**
+     * Attach an image and load from it (BM 0xDD Autostart). With run=false VICE
+     * uses its autoload mode, which attaches to drive 8 and LOADs without RUN.
+     */
+    async autostart(filename, options) {
+        const name = Buffer.from(filename, "utf8");
+        if (name.length === 0 || name.length > 255) {
+            throw new Error("Autostart file names must be 1-255 bytes");
+        }
+        const body = Buffer.alloc(4 + name.length);
+        body[0] = options.run ? 1 : 0;
+        body.writeUInt16LE(options.fileIndex ?? 0, 1);
+        body[3] = name.length;
+        name.copy(body, 4);
+        await this.send(0xDD, body);
+    }
     /**
      * Exit the emulator process (BM 0xBB Quit). The socket will be closed by VICE.
      * Consumers should still call close() to dispose any local resources.
@@ -177,7 +195,9 @@ export class ViceClient {
         body[5] = 0; // comp space
         body.writeUInt16LE(0, 6); // bank
         const frame = await this.send(0x01, body);
-        const len = frame.readUInt16LE(12);
+        // ML is 16 bits wide, so VICE reports a full $0000-$FFFF read as 0; the body length is authoritative.
+        const declared = frame.readUInt16LE(12);
+        const len = Math.min(frame.length - 14, declared === 0 ? 0x10000 : declared);
         return frame.subarray(14, 14 + len);
     }
     async memSet(start, payload) {
@@ -200,7 +220,7 @@ export class ViceClient {
     /** Set the VICE joyport's active-low control byte (BM command 0xA2). */
     async joyportSet(port, activeLowMask) {
         const body = Buffer.alloc(4);
-        body.writeUInt16LE(port, 0);
+        body.writeUInt16LE(port - 1, 0); // VICE joyports are 0-based (JOYPORT_1 = 0, JOYPORT_2 = 1).
         body.writeUInt16LE(activeLowMask & 0xff, 2);
         await this.send(0xA2, body);
     }
@@ -458,12 +478,20 @@ export class ViceClient {
         const innerWidth = body.readUInt16LE(12);
         const innerHeight = body.readUInt16LE(14);
         const bitsPerPixel = body[16] ?? 8;
-        const pixelLength = body.readUInt32LE(17);
-        const pixelStart = 4 + infoLength;
-        if (pixelStart + pixelLength > body.length) {
+        // FL counts only the DW..BP fields; the 4-byte BL field sits between them and the pixels.
+        const pixelLengthOffset = 4 + infoLength;
+        if (body.length < pixelLengthOffset + 4) {
+            throw new Error("Display response length mismatch");
+        }
+        const pixelLength = body.readUInt32LE(pixelLengthOffset);
+        const pixelStart = pixelLengthOffset + 4;
+        const received = body.length - pixelStart;
+        // VICE 3.9/3.10 size the body as 4 + FL + BL, omitting the last 4 pixel bytes; zero-fill only that gap.
+        if (received < pixelLength - 4) {
             throw new Error("Display pixel buffer truncated");
         }
-        const pixels = Buffer.from(body.subarray(pixelStart, pixelStart + pixelLength));
+        const pixels = Buffer.alloc(pixelLength);
+        body.copy(pixels, 0, pixelStart, pixelStart + Math.min(received, pixelLength));
         return {
             debugWidth,
             debugHeight,

package/mcp/schemas/c64_disk.schema.json

@@ -119,7 +119,7 @@
         "integer",
         "null"
       ],
-      "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+      "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
       "minimum": 1,
       "maximum": 255
     },
@@ -421,7 +421,7 @@
               "integer",
               "null"
             ],
-            "description": "Track count (D64 supports 35 or 40; DNP requires explicit tracks).",
+            "description": "Track count (D64 supports 35 to 41; DNP requires explicit tracks).",
             "minimum": 1,
             "maximum": 255
           },

package/mcp/schemas/c64_input.schema.json

@@ -178,7 +178,7 @@
   "required": [
     "op"
   ],
-  "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
+  "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -274,7 +274,7 @@
     },
     {
       "op": "joystick",
-      "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+      "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
       "required": [
         "port",
         "controls",
@@ -285,7 +285,7 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+        "description": "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
         "properties": {
           "op": {
             "const": "joystick"

package/mcp/schemas/c64_program.schema.json

@@ -60,7 +60,7 @@
               "properties": {
                 "type": {
                   "type": "string",
-                  "description": "Assertion type",
+                  "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                   "enum": [
                     "screen_contains",
                     "memory_equals",
@@ -462,7 +462,7 @@
                     "properties": {
                       "type": {
                         "type": "string",
-                        "description": "Assertion type",
+                        "description": "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).",
                         "enum": [
                           "screen_contains",
                           "memory_equals",

package/mcp/schemas/c64_system.schema.json

@@ -22,8 +22,9 @@
     },
     "name": {
       "type": "string",
-      "description": "Unique task name",
-      "minLength": 1
+      "description": "Unique task name (letters, digits, spaces, '_', '-', '.'; must not start with '.' or a space).",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_][A-Za-z0-9_. -]*$"
     },
     "operation": {
       "type": "string",
@@ -264,8 +265,9 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "Unique task name",
-            "minLength": 1
+            "description": "Unique task name (letters, digits, spaces, '_', '-', '.'; must not start with '.' or a space).",
+            "minLength": 1,
+            "pattern": "^[A-Za-z0-9_][A-Za-z0-9_. -]*$"
           },
           "operation": {
             "type": "string",

package/mcp/schemas/c64_vice.schema.json

@@ -11,7 +11,7 @@
     },
     "name": {
       "type": "string",
-      "description": "VICE resource name (example: SidEngine, C64Model).",
+      "description": "VICE resource name (example: SidEngine, SidModel).",
       "minLength": 1,
       "maxLength": 64,
       "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -46,7 +46,7 @@
           },
           "name": {
             "type": "string",
-            "description": "VICE resource name (example: SidEngine, C64Model).",
+            "description": "VICE resource name (example: SidEngine, SidModel).",
             "minLength": 1,
             "maxLength": 64,
             "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"
@@ -76,7 +76,7 @@
           },
           "name": {
             "type": "string",
-            "description": "VICE resource name (example: SidEngine, C64Model).",
+            "description": "VICE resource name (example: SidEngine, SidModel).",
             "minLength": 1,
             "maxLength": 64,
             "pattern": "^[A-Z][A-Za-z0-9_.-]{0,63}$"

package/mcp/server.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "transports": [
     "stdio"