c64bridge 1.0.3 → 1.0.5

package/dist/tools/translation/assembler.js

@@ -31,6 +31,41 @@ var AddressingMode;
     AddressingMode["Relative"] = "relative";
 })(AddressingMode || (AddressingMode = {}));
 const DEFAULT_LOAD_ADDRESS = 0x0801;
+const BASIC_START = 0x0801;
+// "10 SYS0nnnn": link $080C, line 10, SYS token, five digits, end of line, end
+// of program. The digits are the first instruction's address; a fixed width
+// keeps the stub, and so every address after it, the same in both passes.
+function basicSysStub(target) {
+    const digits = String(target & 0xffff).padStart(5, "0");
+    return [0x0c, 0x08, 0x0a, 0x00, 0x9e, ...[...digits].map((digit) => digit.charCodeAt(0)), 0x00, 0x00, 0x00];
+}
+/**
+ * Address to SYS to start a PRG: the target of a leading "SYS <n>" BASIC line
+ * when the PRG loads at $0801, otherwise the load address.
+ */
+export function prgEntryAddress(prg) {
+    const loadAddress = (prg[0] ?? 0) | ((prg[1] ?? 0) << 8);
+    if (loadAddress !== BASIC_START || prg.length < 8) {
+        return loadAddress;
+    }
+    // Skip the link pointer and line number, then expect the SYS token and digits.
+    let index = 6;
+    while (prg[index] === 0x20)
+        index += 1;
+    if (prg[index] !== 0x9e) {
+        return loadAddress;
+    }
+    index += 1;
+    while (prg[index] === 0x20 || prg[index] === 0x28)
+        index += 1;
+    let digits = "";
+    while (index < prg.length && prg[index] >= 0x30 && prg[index] <= 0x39) {
+        digits += String.fromCharCode(prg[index]);
+        index += 1;
+    }
+    const target = Number.parseInt(digits, 10);
+    return digits.length > 0 && target <= 0xffff ? target : loadAddress;
+}
 const MAX_ADDRESS = 0xffff;
 const SINGLE_CHAR_TOKENS = new Set([",", ":", "#", "(", ")", "+", "-", "*", "/", "%", "&", "|", "^", "<", ">", "=", "!", "~"]);
 const MULTI_CHAR_TOKENS = new Set([
@@ -280,6 +315,13 @@ function tokenize(line) {
         }
         if (isDigit(char) || char === "$") {
             const { value, nextIndex } = parseNumberToken(line, index);
+            const digits = line.slice(index, nextIndex);
+            const afterPercent = tokens[tokens.length - 1]?.kind === "punct" && tokens[tokens.length - 1]?.value === "%" && line[index - 1] === "%";
+            if (afterPercent && /^[01]+$/.test(digits)) {
+                tokens.push({ kind: "number", value, binaryValue: parseInt(digits, 2) });
+                index = nextIndex;
+                continue;
+            }
             tokens.push({ kind: "number", value });
             index = nextIndex;
             continue;
@@ -466,10 +508,23 @@ function parseUnaryExpression(stream, terminators) {
     if (!token) {
         throw new Error("Unexpected end of expression");
     }
-    if (token.kind === "punct" && (token.value === "+" || token.value === "-" || token.value === "!" || token.value === "~")) {
+    // In operand position, "<" and ">" are byte selectors and "*" is the current
+    // PC; parseBinaryExpression consumes them as binary operators elsewhere.
+    if (token.kind === "punct" &&
+        (token.value === "+" || token.value === "-" || token.value === "!" || token.value === "~" || token.value === "<" || token.value === ">")) {
         const operand = parseUnaryExpression(stream, terminators);
         return { type: "unary", op: token.value, operand };
     }
+    if (token.kind === "punct" && token.value === "*") {
+        return { type: "symbol", name: "*" };
+    }
+    if (token.kind === "punct" && token.value === "%") {
+        const digits = stream.peek();
+        if (digits?.kind === "number" && digits.binaryValue !== undefined) {
+            stream.consume();
+            return { type: "number", value: digits.binaryValue };
+        }
+    }
     if (token.kind === "punct" && token.value === "(") {
         const expr = parseExpression(stream, new Set([")"]));
         const closing = stream.consume();
@@ -591,17 +646,16 @@ class SymbolTable {
         }
     }
     ensureLabel(label, expected) {
-        const existing = this.get(label);
-        if (existing === undefined) {
-            throw new Error(`Symbol "${label}" was not defined in the first pass`);
-        }
-        if (existing !== expected) {
-            throw new Error(`Symbol "${label}" changed value between passes (expected ${formatHex(existing)}, got ${formatHex(expected)})`);
-        }
+        this.ensureUnchanged(label, expected);
         if (!label.startsWith(".")) {
             this.currentScope = label;
         }
     }
+    // Constant assignments never open a local-label scope (as in ACME and
+    // 64tass), matching setAssignment in the first pass.
+    ensureAssignment(label, expected) {
+        this.ensureUnchanged(label, expected);
+    }
     setAssignment(label, value) {
         if (label.startsWith(".")) {
             if (!this.currentScope) {
@@ -628,6 +682,15 @@ class SymbolTable {
     allGlobals() {
         return this.globals;
     }
+    ensureUnchanged(label, expected) {
+        const existing = this.get(label);
+        if (existing === undefined) {
+            throw new Error(`Symbol "${label}" was not defined in the first pass`);
+        }
+        if (existing !== expected) {
+            throw new Error(`Symbol "${label}" changed value between passes (expected ${formatHex(existing)}, got ${formatHex(expected)})`);
+        }
+    }
     ensureLocalScope(scope) {
         if (!this.locals.has(scope)) {
             this.locals.set(scope, new Map());
@@ -638,21 +701,33 @@ class SymbolTable {
 class Assembler {
     constructor(lines, defaultLoadAddress) {
         this.lines = lines;
+        this.defaultLoadAddress = defaultLoadAddress;
         this.symbolTable = new SymbolTable();
         this.memory = new Uint8Array(0x10000);
         this.written = new Uint8Array(0x10000);
         this.pc = 0;
         this.lowestWritten = MAX_ADDRESS;
         this.highestWritten = 0;
-        this.loadAddress = defaultLoadAddress;
         this.symbolTable.reset();
     }
     runPass(pass) {
-        this.pc = 0;
+        // Code before the first org directive is assembled at the load address.
+        this.pc = this.defaultLoadAddress & 0xffff;
         if (pass === 0) {
             this.symbolTable.reset();
             this.lowestWritten = MAX_ADDRESS;
             this.highestWritten = 0;
+            this.firstInstructionAddress = undefined;
+        }
+        // Loading a PRG at $0801 makes BASIC relink the bytes there as program
+        // lines, which corrupts raw machine code. Code that starts at $0801
+        // without its own org therefore gets a "10 SYS" stub that jumps to the
+        // first instruction, even when data comes before it.
+        if (this.pc === BASIC_START && this.emitsBeforeFirstOrg()) {
+            // Pass 0 does not know the first instruction's address yet; pass 1 uses the address pass 0 recorded.
+            for (const byte of basicSysStub(pass === 1 ? this.firstInstructionAddress ?? 0 : 0)) {
+                this.writeByte(byte, this.lines[0].location);
+            }
         }
         for (const line of this.lines) {
             try {
@@ -667,11 +742,31 @@ class Assembler {
             }
         }
     }
+    emitsBeforeFirstOrg() {
+        for (const line of this.lines) {
+            const statement = line.statement;
+            if (!statement)
+                continue;
+            if (statement.kind === "instruction")
+                return true;
+            if (statement.kind === "assignment" && statement.isLocationCounter)
+                return false;
+            if (statement.kind === "directive") {
+                if (statement.name === "org")
+                    return false;
+                if (statement.name !== "include")
+                    return true;
+            }
+        }
+        return false;
+    }
     buildPrg() {
-        if (this.lowestWritten === MAX_ADDRESS || this.highestWritten < this.loadAddress) {
+        // The PRG spans the bytes actually emitted, so org blocks that only define
+        // labels neither move the load address nor add padding.
+        if (this.lowestWritten > this.highestWritten) {
             return Buffer.alloc(0);
         }
-        const start = Math.min(this.lowestWritten, this.loadAddress);
+        const start = this.lowestWritten;
         const end = this.highestWritten;
         const body = this.memory.subarray(start, end + 1);
         const header = Buffer.alloc(2);
@@ -714,15 +809,12 @@ class Assembler {
         }
         if (statement.isLocationCounter) {
             this.pc = value & 0xffff;
-            if (pass === 0) {
-                this.loadAddress = this.pc;
-            }
         }
         else if (pass === 0) {
             this.symbolTable.setAssignment(statement.target, value);
         }
         else {
-            this.symbolTable.ensureLabel(statement.target, value);
+            this.symbolTable.ensureAssignment(statement.target, value);
         }
     }
     handleDirective(statement, pass, location) {
@@ -736,9 +828,6 @@ class Assembler {
                     throw new AssemblyError("org directive requires a defined value", location);
                 }
                 this.pc = value & 0xffff;
-                if (pass === 0) {
-                    this.loadAddress = this.pc;
-                }
                 break;
             }
             case "byte": {
@@ -831,6 +920,7 @@ class Assembler {
         const info = determineInstruction(statement, pass, this.evaluate.bind(this), this.pc, location);
         statement.resolvedMode = info.mode;
         if (pass === 0) {
+            this.firstInstructionAddress ?? (this.firstInstructionAddress = this.pc);
             this.pc += info.size;
             return;
         }
@@ -889,6 +979,10 @@ class Assembler {
                         return value ? 0 : 1;
                     case "~":
                         return ~value;
+                    case "<":
+                        return value & 0xff;
+                    case ">":
+                        return (value >> 8) & 0xff;
                     default:
                         throw new AssemblyError("Unknown unary operator", location);
                 }
@@ -961,6 +1055,7 @@ class Assembler {
 function determineInstruction(statement, pass, evaluator, locationCounter, location) {
     if (statement.resolvedMode && pass === 1) {
         const value = statement.operand.kind === "none" ? undefined : resolveOperandValue(statement.operand, evaluator, pass, location);
+        assertZeroPageOperand(statement.mnemonic, statement.resolvedMode, value, location);
         const size = instructionSize(statement.resolvedMode);
         return {
             mode: statement.resolvedMode,
@@ -1040,43 +1135,51 @@ function chooseAddressingMode(mnemonic, operand, value, pass, location) {
                 return AddressingMode.Relative;
             }
             if (register === "X") {
-                if (available.has(AddressingMode.ZeroPageX) && value !== undefined && fitsByte(value)) {
-                    return AddressingMode.ZeroPageX;
-                }
-                if (available.has(AddressingMode.AbsoluteX)) {
-                    return AddressingMode.AbsoluteX;
-                }
+                return chooseZeroPageOrAbsolute(mnemonic, available, AddressingMode.ZeroPageX, AddressingMode.AbsoluteX, value, location);
             }
-            else if (register === "Y") {
-                if (available.has(AddressingMode.ZeroPageY) && value !== undefined && fitsByte(value)) {
-                    return AddressingMode.ZeroPageY;
-                }
-                if (available.has(AddressingMode.AbsoluteY)) {
-                    return AddressingMode.AbsoluteY;
-                }
+            if (register === "Y") {
+                return chooseZeroPageOrAbsolute(mnemonic, available, AddressingMode.ZeroPageY, AddressingMode.AbsoluteY, value, location);
             }
-            else if (register === "S") {
-                if (available.has(AddressingMode.ZeroPageS)) {
-                    return AddressingMode.ZeroPageS;
+            if (register === "S") {
+                if (!available.has(AddressingMode.ZeroPageS)) {
+                    throw new AssemblyError(`Instruction ${mnemonic} does not support expr,S addressing`, location);
                 }
+                return AddressingMode.ZeroPageS;
             }
-            else {
-                if (available.has(AddressingMode.ZeroPage) && value !== undefined && fitsByte(value)) {
-                    return AddressingMode.ZeroPage;
-                }
-                if (available.has(AddressingMode.Absolute)) {
-                    return AddressingMode.Absolute;
-                }
-            }
-            if (available.has(AddressingMode.Absolute)) {
-                return AddressingMode.Absolute;
-            }
-            throw new AssemblyError(`Instruction ${mnemonic} cannot resolve addressing mode`, location);
+            return chooseZeroPageOrAbsolute(mnemonic, available, AddressingMode.ZeroPage, AddressingMode.Absolute, value, location);
         }
         default:
             throw new AssemblyError("Unsupported operand kind", location);
     }
 }
+function chooseZeroPageOrAbsolute(mnemonic, available, zeroPageMode, absoluteMode, value, location) {
+    const hasZeroPage = available.has(zeroPageMode);
+    const hasAbsolute = available.has(absoluteMode);
+    if (hasZeroPage && value !== undefined && fitsByte(value)) {
+        return zeroPageMode;
+    }
+    if (hasAbsolute) {
+        return absoluteMode;
+    }
+    // Without an absolute form (e.g. STX zp,Y), a forward reference must be
+    // sized as zero page; the second pass rejects values outside zero page.
+    if (hasZeroPage && value === undefined) {
+        return zeroPageMode;
+    }
+    throw new AssemblyError(`Instruction ${mnemonic} does not support ${absoluteMode} addressing`, location);
+}
+function assertZeroPageOperand(mnemonic, mode, value, location) {
+    const absoluteMode = ZERO_PAGE_TO_ABSOLUTE_MODE.get(mode);
+    if (absoluteMode === undefined || value === undefined || fitsByte(value)) {
+        return;
+    }
+    throw new AssemblyError(`Instruction ${mnemonic} does not support ${absoluteMode} addressing (operand ${formatHex(value)} is outside zero page)`, location);
+}
+const ZERO_PAGE_TO_ABSOLUTE_MODE = new Map([
+    [AddressingMode.ZeroPage, AddressingMode.Absolute],
+    [AddressingMode.ZeroPageX, AddressingMode.AbsoluteX],
+    [AddressingMode.ZeroPageY, AddressingMode.AbsoluteY],
+]);
 function instructionSize(mode) {
     switch (mode) {
         case AddressingMode.Implied:

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,7 +107,9 @@ 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
@@ -91,6 +118,9 @@ function tokenize(content) {
         }
         const plainChar = (!inString && !inRemark ? upper[index] : char) ?? char;
         bytes.push(asciiToPetscii(plainChar));
+        if (inData && !inString && plainChar === ":") {
+            inData = false;
+        }
         index += 1;
     }
     if (bytes.length === 0) {
@@ -112,7 +142,7 @@ function buildTokenTable() {
         ["END", 0x80],
         ["FOR", 0x81],
         ["NEXT", 0x82],
-        ["DATA", 0x83],
+        ["DATA", DATA_TOKEN],
         ["INPUT#", 0x84],
         ["INPUT", 0x85],
         ["DIM", 0x86],
@@ -134,7 +164,7 @@ function buildTokenTable() {
         ["DEF", 0x96],
         ["POKE", 0x97],
         ["PRINT#", 0x98],
-        ["PRINT", 0x99],
+        ["PRINT", PRINT_TOKEN],
         ["CONT", 0x9a],
         ["LIST", 0x9b],
         ["CLR", 0x9c],

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/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

@@ -187,7 +187,7 @@ export class ViceMockServer {
                 const end = body.readUInt16LE(3);
                 const length = Math.max(0, 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];
                 }
@@ -359,7 +359,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 +373,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) {

package/dist/vice/viceClient.js

@@ -177,7 +177,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 +202,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 +460,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_config.schema.json

@@ -53,7 +53,7 @@
         "boolean",
         "null"
       ],
-      "description": "When true, save the restored configuration to flash immediately.",
+      "description": "When true, save the restored configuration to flash immediately (C64U/U64 and U2 only).",
       "default": false
     },
     "root": {
@@ -452,7 +452,7 @@
               "boolean",
               "null"
             ],
-            "description": "When true, save the restored configuration to flash immediately.",
+            "description": "When true, save the restored configuration to flash immediately (C64U/U64 and U2 only).",
             "default": false
           },
           "op": {