c64bridge 0.9.1 → 0.9.3

package/dist/tools/{assember.js → translation/assembler.js}

@@ -6,6 +6,7 @@ Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
+import { OPCODE_INVENTORY } from "./opcodeInventory.js";
 export class AssemblyError extends Error {
     constructor(message, location) {
         super(`${location.file}:${location.line}: ${message}`);
@@ -20,6 +21,7 @@ var AddressingMode;
     AddressingMode["ZeroPage"] = "zeroPage";
     AddressingMode["ZeroPageX"] = "zeroPageX";
     AddressingMode["ZeroPageY"] = "zeroPageY";
+    AddressingMode["ZeroPageS"] = "zeroPageS";
     AddressingMode["Absolute"] = "absolute";
     AddressingMode["AbsoluteX"] = "absoluteX";
     AddressingMode["AbsoluteY"] = "absoluteY";
@@ -519,7 +521,19 @@ function parseOperand(stream) {
     }
     if (first.kind === "punct" && first.value === "(") {
         stream.consumePunct("(");
-        const expr = parseExpression(stream, new Set([")"]));
+        const expr = parseExpression(stream, new Set([",", ")"]));
+        if (stream.peek()?.kind === "punct" && stream.peek()?.value === ",") {
+            stream.consumePunct(",");
+            const register = stream.consumeSymbol("Expected X before ')'").toUpperCase();
+            if (register !== "X") {
+                throw new Error("Only X is allowed inside pre-indexed indirect operands");
+            }
+            stream.consumePunct(")", "Expected ')' to close indirect operand");
+            if (!stream.isAtEnd()) {
+                throw new Error("Unexpected tokens after indirect operand");
+            }
+            return { kind: "indirect", expr, register: "X" };
+        }
         stream.consumePunct(")", "Expected ')' to close indirect operand");
         if (stream.isAtEnd()) {
             return { kind: "indirect", expr };
@@ -545,9 +559,9 @@ function parseOperand(stream) {
     const next = stream.peek();
     if (next && next.kind === "punct" && next.value === ",") {
         stream.consumePunct(",");
-        const register = stream.consumeSymbol("Expected X or Y after comma").toUpperCase();
-        if (register !== "X" && register !== "Y") {
-            throw new Error("Only X or Y are allowed after comma");
+        const register = stream.consumeSymbol("Expected X, Y, or S after comma").toUpperCase();
+        if (register !== "X" && register !== "Y" && register !== "S") {
+            throw new Error("Only X, Y, or S are allowed after comma");
         }
         return { kind: "expression", expr, register };
     }
@@ -830,6 +844,7 @@ class Assembler {
             case AddressingMode.ZeroPage:
             case AddressingMode.ZeroPageX:
             case AddressingMode.ZeroPageY:
+            case AddressingMode.ZeroPageS:
             case AddressingMode.IndirectX:
             case AddressingMode.IndirectY:
                 this.writeByte(info.value ?? 0, location);
@@ -1040,6 +1055,11 @@ function chooseAddressingMode(mnemonic, operand, value, pass, location) {
                     return AddressingMode.AbsoluteY;
                 }
             }
+            else if (register === "S") {
+                if (available.has(AddressingMode.ZeroPageS)) {
+                    return AddressingMode.ZeroPageS;
+                }
+            }
             else {
                 if (available.has(AddressingMode.ZeroPage) && value !== undefined && fitsByte(value)) {
                     return AddressingMode.ZeroPage;
@@ -1066,6 +1086,7 @@ function instructionSize(mode) {
         case AddressingMode.ZeroPage:
         case AddressingMode.ZeroPageX:
         case AddressingMode.ZeroPageY:
+        case AddressingMode.ZeroPageS:
         case AddressingMode.IndirectX:
         case AddressingMode.IndirectY:
         case AddressingMode.Relative:
@@ -1095,6 +1116,7 @@ function normalizeOperandValue(mode, value, locationCounterOrLocation, locationM
         case AddressingMode.ZeroPage:
         case AddressingMode.ZeroPageX:
         case AddressingMode.ZeroPageY:
+        case AddressingMode.ZeroPageS:
         case AddressingMode.IndirectX:
         case AddressingMode.IndirectY:
             if (value === undefined)
@@ -1141,168 +1163,40 @@ function fitsByte(value) {
 function formatHex(value) {
     return `$${value.toString(16).toUpperCase().padStart(4, "0")}`;
 }
+const OPCODE_MODE_TO_ADDRESSING_MODE = {
+    implied: AddressingMode.Implied,
+    accumulator: AddressingMode.Accumulator,
+    immediate: AddressingMode.Immediate,
+    zeroPage: AddressingMode.ZeroPage,
+    zeroPageX: AddressingMode.ZeroPageX,
+    zeroPageY: AddressingMode.ZeroPageY,
+    zeroPageS: AddressingMode.ZeroPageS,
+    absolute: AddressingMode.Absolute,
+    absoluteX: AddressingMode.AbsoluteX,
+    absoluteY: AddressingMode.AbsoluteY,
+    indirect: AddressingMode.Indirect,
+    indirectX: AddressingMode.IndirectX,
+    indirectY: AddressingMode.IndirectY,
+    relative: AddressingMode.Relative,
+};
 function buildInstructionTable() {
     const table = new Map();
-    for (const entry of INSTRUCTION_DATA) {
-        const mnemonic = entry.mnemonic;
-        if (!table.has(mnemonic)) {
-            table.set(mnemonic, new Map());
+    const entryByMnemonicAndMode = new Map();
+    for (const entry of OPCODE_INVENTORY) {
+        const mode = OPCODE_MODE_TO_ADDRESSING_MODE[entry.mode];
+        const key = `${entry.mnemonic}\u0000${mode}`;
+        const existing = entryByMnemonicAndMode.get(key);
+        // The inventory is sorted by opcode, but assembly should prefer official
+        // encodings over undocumented aliases for duplicate mnemonic/mode pairs.
+        if (existing && (!existing.illegal || entry.illegal)) {
+            continue;
+        }
+        entryByMnemonicAndMode.set(key, { opcode: entry.opcode, illegal: entry.illegal });
+        if (!table.has(entry.mnemonic)) {
+            table.set(entry.mnemonic, new Map());
         }
-        table.get(mnemonic).set(entry.mode, entry.opcode);
+        table.get(entry.mnemonic).set(mode, entry.opcode);
     }
     return table;
 }
-const INSTRUCTION_DATA = [
-    { mnemonic: "ADC", mode: AddressingMode.Immediate, opcode: 0x69 },
-    { mnemonic: "ADC", mode: AddressingMode.ZeroPage, opcode: 0x65 },
-    { mnemonic: "ADC", mode: AddressingMode.ZeroPageX, opcode: 0x75 },
-    { mnemonic: "ADC", mode: AddressingMode.Absolute, opcode: 0x6d },
-    { mnemonic: "ADC", mode: AddressingMode.AbsoluteX, opcode: 0x7d },
-    { mnemonic: "ADC", mode: AddressingMode.AbsoluteY, opcode: 0x79 },
-    { mnemonic: "ADC", mode: AddressingMode.IndirectX, opcode: 0x61 },
-    { mnemonic: "ADC", mode: AddressingMode.IndirectY, opcode: 0x71 },
-    { mnemonic: "AND", mode: AddressingMode.Immediate, opcode: 0x29 },
-    { mnemonic: "AND", mode: AddressingMode.ZeroPage, opcode: 0x25 },
-    { mnemonic: "AND", mode: AddressingMode.ZeroPageX, opcode: 0x35 },
-    { mnemonic: "AND", mode: AddressingMode.Absolute, opcode: 0x2d },
-    { mnemonic: "AND", mode: AddressingMode.AbsoluteX, opcode: 0x3d },
-    { mnemonic: "AND", mode: AddressingMode.AbsoluteY, opcode: 0x39 },
-    { mnemonic: "AND", mode: AddressingMode.IndirectX, opcode: 0x21 },
-    { mnemonic: "AND", mode: AddressingMode.IndirectY, opcode: 0x31 },
-    { mnemonic: "ASL", mode: AddressingMode.Accumulator, opcode: 0x0a },
-    { mnemonic: "ASL", mode: AddressingMode.ZeroPage, opcode: 0x06 },
-    { mnemonic: "ASL", mode: AddressingMode.ZeroPageX, opcode: 0x16 },
-    { mnemonic: "ASL", mode: AddressingMode.Absolute, opcode: 0x0e },
-    { mnemonic: "ASL", mode: AddressingMode.AbsoluteX, opcode: 0x1e },
-    { mnemonic: "BIT", mode: AddressingMode.ZeroPage, opcode: 0x24 },
-    { mnemonic: "BIT", mode: AddressingMode.Absolute, opcode: 0x2c },
-    { mnemonic: "BPL", mode: AddressingMode.Relative, opcode: 0x10 },
-    { mnemonic: "BMI", mode: AddressingMode.Relative, opcode: 0x30 },
-    { mnemonic: "BVC", mode: AddressingMode.Relative, opcode: 0x50 },
-    { mnemonic: "BVS", mode: AddressingMode.Relative, opcode: 0x70 },
-    { mnemonic: "BCC", mode: AddressingMode.Relative, opcode: 0x90 },
-    { mnemonic: "BCS", mode: AddressingMode.Relative, opcode: 0xb0 },
-    { mnemonic: "BNE", mode: AddressingMode.Relative, opcode: 0xd0 },
-    { mnemonic: "BEQ", mode: AddressingMode.Relative, opcode: 0xf0 },
-    { mnemonic: "BRK", mode: AddressingMode.Implied, opcode: 0x00 },
-    { mnemonic: "CLC", mode: AddressingMode.Implied, opcode: 0x18 },
-    { mnemonic: "CLD", mode: AddressingMode.Implied, opcode: 0xd8 },
-    { mnemonic: "CLI", mode: AddressingMode.Implied, opcode: 0x58 },
-    { mnemonic: "CLV", mode: AddressingMode.Implied, opcode: 0xb8 },
-    { mnemonic: "CMP", mode: AddressingMode.Immediate, opcode: 0xc9 },
-    { mnemonic: "CMP", mode: AddressingMode.ZeroPage, opcode: 0xc5 },
-    { mnemonic: "CMP", mode: AddressingMode.ZeroPageX, opcode: 0xd5 },
-    { mnemonic: "CMP", mode: AddressingMode.Absolute, opcode: 0xcd },
-    { mnemonic: "CMP", mode: AddressingMode.AbsoluteX, opcode: 0xdd },
-    { mnemonic: "CMP", mode: AddressingMode.AbsoluteY, opcode: 0xd9 },
-    { mnemonic: "CMP", mode: AddressingMode.IndirectX, opcode: 0xc1 },
-    { mnemonic: "CMP", mode: AddressingMode.IndirectY, opcode: 0xd1 },
-    { mnemonic: "CPX", mode: AddressingMode.Immediate, opcode: 0xe0 },
-    { mnemonic: "CPX", mode: AddressingMode.ZeroPage, opcode: 0xe4 },
-    { mnemonic: "CPX", mode: AddressingMode.Absolute, opcode: 0xec },
-    { mnemonic: "CPY", mode: AddressingMode.Immediate, opcode: 0xc0 },
-    { mnemonic: "CPY", mode: AddressingMode.ZeroPage, opcode: 0xc4 },
-    { mnemonic: "CPY", mode: AddressingMode.Absolute, opcode: 0xcc },
-    { mnemonic: "DEC", mode: AddressingMode.ZeroPage, opcode: 0xc6 },
-    { mnemonic: "DEC", mode: AddressingMode.ZeroPageX, opcode: 0xd6 },
-    { mnemonic: "DEC", mode: AddressingMode.Absolute, opcode: 0xce },
-    { mnemonic: "DEC", mode: AddressingMode.AbsoluteX, opcode: 0xde },
-    { mnemonic: "DEX", mode: AddressingMode.Implied, opcode: 0xca },
-    { mnemonic: "DEY", mode: AddressingMode.Implied, opcode: 0x88 },
-    { mnemonic: "EOR", mode: AddressingMode.Immediate, opcode: 0x49 },
-    { mnemonic: "EOR", mode: AddressingMode.ZeroPage, opcode: 0x45 },
-    { mnemonic: "EOR", mode: AddressingMode.ZeroPageX, opcode: 0x55 },
-    { mnemonic: "EOR", mode: AddressingMode.Absolute, opcode: 0x4d },
-    { mnemonic: "EOR", mode: AddressingMode.AbsoluteX, opcode: 0x5d },
-    { mnemonic: "EOR", mode: AddressingMode.AbsoluteY, opcode: 0x59 },
-    { mnemonic: "EOR", mode: AddressingMode.IndirectX, opcode: 0x41 },
-    { mnemonic: "EOR", mode: AddressingMode.IndirectY, opcode: 0x51 },
-    { mnemonic: "INC", mode: AddressingMode.ZeroPage, opcode: 0xe6 },
-    { mnemonic: "INC", mode: AddressingMode.ZeroPageX, opcode: 0xf6 },
-    { mnemonic: "INC", mode: AddressingMode.Absolute, opcode: 0xee },
-    { mnemonic: "INC", mode: AddressingMode.AbsoluteX, opcode: 0xfe },
-    { mnemonic: "INX", mode: AddressingMode.Implied, opcode: 0xe8 },
-    { mnemonic: "INY", mode: AddressingMode.Implied, opcode: 0xc8 },
-    { mnemonic: "JMP", mode: AddressingMode.Absolute, opcode: 0x4c },
-    { mnemonic: "JMP", mode: AddressingMode.Indirect, opcode: 0x6c },
-    { mnemonic: "JSR", mode: AddressingMode.Absolute, opcode: 0x20 },
-    { mnemonic: "LDA", mode: AddressingMode.Immediate, opcode: 0xa9 },
-    { mnemonic: "LDA", mode: AddressingMode.ZeroPage, opcode: 0xa5 },
-    { mnemonic: "LDA", mode: AddressingMode.ZeroPageX, opcode: 0xb5 },
-    { mnemonic: "LDA", mode: AddressingMode.Absolute, opcode: 0xad },
-    { mnemonic: "LDA", mode: AddressingMode.AbsoluteX, opcode: 0xbd },
-    { mnemonic: "LDA", mode: AddressingMode.AbsoluteY, opcode: 0xb9 },
-    { mnemonic: "LDA", mode: AddressingMode.IndirectX, opcode: 0xa1 },
-    { mnemonic: "LDA", mode: AddressingMode.IndirectY, opcode: 0xb1 },
-    { mnemonic: "LDX", mode: AddressingMode.Immediate, opcode: 0xa2 },
-    { mnemonic: "LDX", mode: AddressingMode.ZeroPage, opcode: 0xa6 },
-    { mnemonic: "LDX", mode: AddressingMode.ZeroPageY, opcode: 0xb6 },
-    { mnemonic: "LDX", mode: AddressingMode.Absolute, opcode: 0xae },
-    { mnemonic: "LDX", mode: AddressingMode.AbsoluteY, opcode: 0xbe },
-    { mnemonic: "LDY", mode: AddressingMode.Immediate, opcode: 0xa0 },
-    { mnemonic: "LDY", mode: AddressingMode.ZeroPage, opcode: 0xa4 },
-    { mnemonic: "LDY", mode: AddressingMode.ZeroPageX, opcode: 0xb4 },
-    { mnemonic: "LDY", mode: AddressingMode.Absolute, opcode: 0xac },
-    { mnemonic: "LDY", mode: AddressingMode.AbsoluteX, opcode: 0xbc },
-    { mnemonic: "LSR", mode: AddressingMode.Accumulator, opcode: 0x4a },
-    { mnemonic: "LSR", mode: AddressingMode.ZeroPage, opcode: 0x46 },
-    { mnemonic: "LSR", mode: AddressingMode.ZeroPageX, opcode: 0x56 },
-    { mnemonic: "LSR", mode: AddressingMode.Absolute, opcode: 0x4e },
-    { mnemonic: "LSR", mode: AddressingMode.AbsoluteX, opcode: 0x5e },
-    { mnemonic: "NOP", mode: AddressingMode.Implied, opcode: 0xea },
-    { mnemonic: "ORA", mode: AddressingMode.Immediate, opcode: 0x09 },
-    { mnemonic: "ORA", mode: AddressingMode.ZeroPage, opcode: 0x05 },
-    { mnemonic: "ORA", mode: AddressingMode.ZeroPageX, opcode: 0x15 },
-    { mnemonic: "ORA", mode: AddressingMode.Absolute, opcode: 0x0d },
-    { mnemonic: "ORA", mode: AddressingMode.AbsoluteX, opcode: 0x1d },
-    { mnemonic: "ORA", mode: AddressingMode.AbsoluteY, opcode: 0x19 },
-    { mnemonic: "ORA", mode: AddressingMode.IndirectX, opcode: 0x01 },
-    { mnemonic: "ORA", mode: AddressingMode.IndirectY, opcode: 0x11 },
-    { mnemonic: "PHA", mode: AddressingMode.Implied, opcode: 0x48 },
-    { mnemonic: "PHP", mode: AddressingMode.Implied, opcode: 0x08 },
-    { mnemonic: "PLA", mode: AddressingMode.Implied, opcode: 0x68 },
-    { mnemonic: "PLP", mode: AddressingMode.Implied, opcode: 0x28 },
-    { mnemonic: "ROL", mode: AddressingMode.Accumulator, opcode: 0x2a },
-    { mnemonic: "ROL", mode: AddressingMode.ZeroPage, opcode: 0x26 },
-    { mnemonic: "ROL", mode: AddressingMode.ZeroPageX, opcode: 0x36 },
-    { mnemonic: "ROL", mode: AddressingMode.Absolute, opcode: 0x2e },
-    { mnemonic: "ROL", mode: AddressingMode.AbsoluteX, opcode: 0x3e },
-    { mnemonic: "ROR", mode: AddressingMode.Accumulator, opcode: 0x6a },
-    { mnemonic: "ROR", mode: AddressingMode.ZeroPage, opcode: 0x66 },
-    { mnemonic: "ROR", mode: AddressingMode.ZeroPageX, opcode: 0x76 },
-    { mnemonic: "ROR", mode: AddressingMode.Absolute, opcode: 0x6e },
-    { mnemonic: "ROR", mode: AddressingMode.AbsoluteX, opcode: 0x7e },
-    { mnemonic: "RTI", mode: AddressingMode.Implied, opcode: 0x40 },
-    { mnemonic: "RTS", mode: AddressingMode.Implied, opcode: 0x60 },
-    { mnemonic: "SBC", mode: AddressingMode.Immediate, opcode: 0xe9 },
-    { mnemonic: "SBC", mode: AddressingMode.ZeroPage, opcode: 0xe5 },
-    { mnemonic: "SBC", mode: AddressingMode.ZeroPageX, opcode: 0xf5 },
-    { mnemonic: "SBC", mode: AddressingMode.Absolute, opcode: 0xed },
-    { mnemonic: "SBC", mode: AddressingMode.AbsoluteX, opcode: 0xfd },
-    { mnemonic: "SBC", mode: AddressingMode.AbsoluteY, opcode: 0xf9 },
-    { mnemonic: "SBC", mode: AddressingMode.IndirectX, opcode: 0xe1 },
-    { mnemonic: "SBC", mode: AddressingMode.IndirectY, opcode: 0xf1 },
-    { mnemonic: "SEC", mode: AddressingMode.Implied, opcode: 0x38 },
-    { mnemonic: "SED", mode: AddressingMode.Implied, opcode: 0xf8 },
-    { mnemonic: "SEI", mode: AddressingMode.Implied, opcode: 0x78 },
-    { mnemonic: "STA", mode: AddressingMode.ZeroPage, opcode: 0x85 },
-    { mnemonic: "STA", mode: AddressingMode.ZeroPageX, opcode: 0x95 },
-    { mnemonic: "STA", mode: AddressingMode.Absolute, opcode: 0x8d },
-    { mnemonic: "STA", mode: AddressingMode.AbsoluteX, opcode: 0x9d },
-    { mnemonic: "STA", mode: AddressingMode.AbsoluteY, opcode: 0x99 },
-    { mnemonic: "STA", mode: AddressingMode.IndirectX, opcode: 0x81 },
-    { mnemonic: "STA", mode: AddressingMode.IndirectY, opcode: 0x91 },
-    { mnemonic: "STX", mode: AddressingMode.ZeroPage, opcode: 0x86 },
-    { mnemonic: "STX", mode: AddressingMode.ZeroPageY, opcode: 0x96 },
-    { mnemonic: "STX", mode: AddressingMode.Absolute, opcode: 0x8e },
-    { mnemonic: "STY", mode: AddressingMode.ZeroPage, opcode: 0x84 },
-    { mnemonic: "STY", mode: AddressingMode.ZeroPageX, opcode: 0x94 },
-    { mnemonic: "STY", mode: AddressingMode.Absolute, opcode: 0x8c },
-    { mnemonic: "TAX", mode: AddressingMode.Implied, opcode: 0xaa },
-    { mnemonic: "TAY", mode: AddressingMode.Implied, opcode: 0xa8 },
-    { mnemonic: "TSX", mode: AddressingMode.Implied, opcode: 0xba },
-    { mnemonic: "TXA", mode: AddressingMode.Implied, opcode: 0x8a },
-    { mnemonic: "TXS", mode: AddressingMode.Implied, opcode: 0x9a },
-    { mnemonic: "TYA", mode: AddressingMode.Implied, opcode: 0x98 },
-];
 const INSTRUCTION_TABLE = buildInstructionTable();

package/dist/tools/{basicTokenizer.js → translation/basicTokenizer.js}

@@ -6,7 +6,7 @@ Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
-import { asciiToPetscii, encodeStringWithNames } from "../petscii.js";
+import { asciiToPetscii, encodeStringWithNames } from "../../petscii.js";
 const DEFAULT_START_ADDRESS = 0x0801;
 const REM_TOKEN = 0x8f;
 const TOKEN_TABLE = buildTokenTable();

package/dist/tools/translation/disassembler.js

@@ -0,0 +1,150 @@
+/**
+ * 6502/6510 disassembler covering the full 256-opcode space, including
+ * undocumented (illegal) opcodes. Mnemonic naming follows the canonical
+ * convention used by the 1541U monitor (HLT->JAM, ASO->SLO, LSE->SRE,
+ * DCM->DCP, INS->ISC).
+ */
+import { OpcodeAddressingMode as Mode, OPCODES_BY_BYTE as OPCODES, opcodeSize as modeSize, } from "./opcodeInventory.js";
+function hex2(v) {
+    return v.toString(16).toUpperCase().padStart(2, "0");
+}
+function hex4(v) {
+    return v.toString(16).toUpperCase().padStart(4, "0");
+}
+function labelOrHex4(addr, symbols) {
+    const label = symbols?.get(addr);
+    return label ? `${label} ($${hex4(addr)})` : `$${hex4(addr)}`;
+}
+function formatOperand(mode, bytes, offset, instrAddr, symbols) {
+    switch (mode) {
+        case Mode.Imp:
+            return "";
+        case Mode.Acc:
+            return "A";
+        case Mode.Imm:
+            return `#$${hex2(bytes[offset + 1] ?? 0)}`;
+        case Mode.Zp:
+            return `$${hex2(bytes[offset + 1] ?? 0)}`;
+        case Mode.ZpX:
+            return `$${hex2(bytes[offset + 1] ?? 0)},X`;
+        case Mode.ZpY:
+            return `$${hex2(bytes[offset + 1] ?? 0)},Y`;
+        case Mode.ZpS:
+            return `$${hex2(bytes[offset + 1] ?? 0)},S`;
+        case Mode.Rel: {
+            const rel = bytes[offset + 1] ?? 0;
+            const signed = rel >= 0x80 ? rel - 0x100 : rel;
+            const target = (instrAddr + 2 + signed) & 0xffff;
+            return labelOrHex4(target, symbols);
+        }
+        case Mode.Abs: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return labelOrHex4(addr, symbols);
+        }
+        case Mode.AbsX: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return `${labelOrHex4(addr, symbols)},X`;
+        }
+        case Mode.AbsY: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return `${labelOrHex4(addr, symbols)},Y`;
+        }
+        case Mode.Ind: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return `($${hex4(addr)})`;
+        }
+        case Mode.IndX:
+            return `($${hex2(bytes[offset + 1] ?? 0)},X)`;
+        case Mode.IndY:
+            return `($${hex2(bytes[offset + 1] ?? 0)}),Y`;
+    }
+}
+/**
+ * Disassemble a block of 6502/6510 bytes.
+ *
+ * @param bytes               Raw memory bytes (may be longer than needed)
+ * @param baseAddress         The C64 memory address of `bytes[0]`
+ * @param countOrOptions      Either a max-instruction count (legacy form) or an options object
+ * @param symbols             Optional address->label map (legacy positional form)
+ */
+export function disassemble(bytes, baseAddress, countOrOptions, symbols) {
+    const options = typeof countOrOptions === "object" && countOrOptions !== null
+        ? countOrOptions
+        : { count: countOrOptions, symbols };
+    const limit = options.count ?? Infinity;
+    const symMap = options.symbols ?? symbols;
+    const allowUndocumented = options.allowUndocumented !== false;
+    const lines = [];
+    let offset = 0;
+    while (offset < bytes.length && lines.length < limit) {
+        const instrAddr = (baseAddress + offset) & 0xffff;
+        const opcode = bytes[offset] ?? 0;
+        const op = OPCODES[opcode];
+        const label = symMap?.get(instrAddr);
+        if (op.illegal && !allowUndocumented) {
+            lines.push({
+                address: instrAddr,
+                bytes: [opcode],
+                label,
+                mnemonic: "???",
+                operand: `$${hex2(opcode)}`,
+                undocumented: true,
+            });
+            offset += 1;
+            continue;
+        }
+        const size = modeSize(op.mode);
+        const instrBytes = [];
+        for (let i = 0; i < size && offset + i < bytes.length; i += 1) {
+            instrBytes.push(bytes[offset + i] ?? 0);
+        }
+        const operand = formatOperand(op.mode, bytes, offset, instrAddr, symMap);
+        lines.push({
+            address: instrAddr,
+            bytes: instrBytes,
+            label,
+            mnemonic: op.mnemonic,
+            operand,
+            undocumented: op.illegal,
+        });
+        offset += size;
+    }
+    return lines;
+}
+/**
+ * Render disassembly lines as a human-readable string.
+ * Format: [label:\n] $ADDR  XX XX XX  MNEM operand   ; *undocumented*
+ */
+export function formatDisassembly(lines) {
+    const parts = [];
+    for (const line of lines) {
+        if (line.label) {
+            parts.push(`${line.label}:`);
+        }
+        const addrStr = `$${hex4(line.address)}`;
+        const byteStr = line.bytes.map((b) => hex2(b)).join(" ").padEnd(8);
+        const mnemonic = line.undocumented ? `${line.mnemonic}*` : line.mnemonic;
+        const instrStr = line.operand
+            ? `${mnemonic} ${line.operand}`
+            : mnemonic;
+        parts.push(`  ${addrStr}  ${byteStr}  ${instrStr}`);
+    }
+    return parts.join("\n");
+}
+/** Returns true when the opcode is undocumented per the 1541U reference. */
+export function isUndocumentedOpcode(opcode) {
+    return OPCODES[opcode & 0xff].illegal;
+}
+/** Lookup helper used by tests to verify table coverage. */
+export function opcodeMetadata(opcode) {
+    const entry = OPCODES[opcode & 0xff];
+    return { mnemonic: entry.mnemonic, undocumented: entry.illegal, size: modeSize(entry.mode) };
+}

package/dist/tools/translation/opcodeInventory.js

@@ -0,0 +1,126 @@
+/**
+ * Shared 6502/6510 opcode inventory.
+ *
+ * Entries are sorted by increasing binary opcode and cover the complete
+ * 256-byte opcode space, including undocumented opcodes. Mnemonic naming
+ * follows the canonical 1541U monitor convention:
+ * HLT -> JAM, ASO -> SLO, LSE -> SRE, DCM -> DCP, INS -> ISC.
+ */
+export const OpcodeAddressingMode = {
+    Imp: "implied",
+    Acc: "accumulator",
+    Imm: "immediate",
+    Zp: "zeroPage",
+    ZpX: "zeroPageX",
+    ZpY: "zeroPageY",
+    ZpS: "zeroPageS",
+    Rel: "relative",
+    Abs: "absolute",
+    AbsX: "absoluteX",
+    AbsY: "absoluteY",
+    Ind: "indirect",
+    IndX: "indirectX",
+    IndY: "indirectY",
+};
+const M = OpcodeAddressingMode;
+const OPCODE_ROWS = [
+    // 0x00-0x0F
+    [["BRK", M.Imp], ["ORA", M.IndX], ["HLT", M.Imp], ["ASO", M.IndX], ["NOP", M.Zp], ["ORA", M.Zp], ["ASL", M.Zp], ["ASO", M.Zp], ["PHP", M.Imp], ["ORA", M.Imm], ["ASL", M.Acc], ["ANC", M.Imm], ["NOP", M.Abs], ["ORA", M.Abs], ["ASL", M.Abs], ["ASO", M.Abs]],
+    // 0x10-0x1F
+    [["BPL", M.Rel], ["ORA", M.IndY], ["HLT", M.Imp], ["ASO", M.IndY], ["NOP", M.ZpX], ["ORA", M.ZpX], ["ASL", M.ZpX], ["ASO", M.ZpX], ["CLC", M.Imp], ["ORA", M.AbsY], ["NOP", M.Imp], ["ASO", M.AbsY], ["NOP", M.AbsX], ["ORA", M.AbsX], ["ASL", M.AbsX], ["ASO", M.AbsX]],
+    // 0x20-0x2F
+    [["JSR", M.Abs], ["AND", M.IndX], ["HLT", M.Imp], ["RLA", M.IndX], ["BIT", M.Zp], ["AND", M.Zp], ["ROL", M.Zp], ["RLA", M.Zp], ["PLP", M.Imp], ["AND", M.Imm], ["ROL", M.Acc], ["ANC", M.Imm], ["BIT", M.Abs], ["AND", M.Abs], ["ROL", M.Abs], ["RLA", M.Abs]],
+    // 0x30-0x3F
+    [["BMI", M.Rel], ["AND", M.IndY], ["HLT", M.Imp], ["RLA", M.IndY], ["NOP", M.ZpX], ["AND", M.ZpX], ["ROL", M.ZpX], ["RLA", M.ZpX], ["SEC", M.Imp], ["AND", M.AbsY], ["NOP", M.Imp], ["RLA", M.AbsY], ["NOP", M.AbsX], ["AND", M.AbsX], ["ROL", M.AbsX], ["RLA", M.AbsX]],
+    // 0x40-0x4F
+    [["RTI", M.Imp], ["EOR", M.IndX], ["HLT", M.Imp], ["LSE", M.IndX], ["NOP", M.Zp], ["EOR", M.Zp], ["LSR", M.Zp], ["LSE", M.Zp], ["PHA", M.Imp], ["EOR", M.Imm], ["LSR", M.Acc], ["ALR", M.Imm], ["JMP", M.Abs], ["EOR", M.Abs], ["LSR", M.Abs], ["LSE", M.Abs]],
+    // 0x50-0x5F
+    [["BVC", M.Rel], ["EOR", M.IndY], ["HLT", M.Imp], ["LSE", M.IndY], ["NOP", M.ZpX], ["EOR", M.ZpX], ["LSR", M.ZpX], ["LSE", M.ZpX], ["CLI", M.Imp], ["EOR", M.AbsY], ["NOP", M.Imp], ["LSE", M.AbsY], ["NOP", M.AbsX], ["EOR", M.AbsX], ["LSR", M.AbsX], ["LSE", M.AbsX]],
+    // 0x60-0x6F
+    [["RTS", M.Imp], ["ADC", M.IndX], ["HLT", M.Imp], ["RRA", M.IndX], ["NOP", M.Zp], ["ADC", M.Zp], ["ROR", M.Zp], ["RRA", M.Zp], ["PLA", M.Imp], ["ADC", M.Imm], ["ROR", M.Acc], ["ARR", M.Imm], ["JMP", M.Ind], ["ADC", M.Abs], ["ROR", M.Abs], ["RRA", M.Abs]],
+    // 0x70-0x7F
+    [["BVS", M.Rel], ["ADC", M.IndY], ["HLT", M.Imp], ["RRA", M.IndY], ["NOP", M.ZpX], ["ADC", M.ZpX], ["ROR", M.ZpX], ["RRA", M.ZpX], ["SEI", M.Imp], ["ADC", M.AbsY], ["NOP", M.Imp], ["RRA", M.AbsY], ["NOP", M.AbsX], ["ADC", M.AbsX], ["ROR", M.AbsX], ["RRA", M.AbsX]],
+    // 0x80-0x8F
+    [["NOP", M.Imm], ["STA", M.IndX], ["NOP", M.Imm], ["SAX", M.IndX], ["STY", M.Zp], ["STA", M.Zp], ["STX", M.Zp], ["SAX", M.Zp], ["DEY", M.Imp], ["NOP", M.Imm], ["TXA", M.Imp], ["XAA", M.Imm], ["STY", M.Abs], ["STA", M.Abs], ["STX", M.Abs], ["SAX", M.Abs]],
+    // 0x90-0x9F
+    [["BCC", M.Rel], ["STA", M.IndY], ["HLT", M.Imp], ["AHX", M.IndY], ["STY", M.ZpX], ["STA", M.ZpX], ["STX", M.ZpY], ["SAX", M.ZpY], ["TYA", M.Imp], ["STA", M.AbsY], ["TXS", M.Imp], ["TAS", M.AbsY], ["SHY", M.AbsX], ["STA", M.AbsX], ["SHX", M.AbsY], ["AHX", M.AbsY]],
+    // 0xA0-0xAF
+    [["LDY", M.Imm], ["LDA", M.IndX], ["LDX", M.Imm], ["LAX", M.IndX], ["LDY", M.Zp], ["LDA", M.Zp], ["LDX", M.Zp], ["LAX", M.Zp], ["TAY", M.Imp], ["LDA", M.Imm], ["TAX", M.Imp], ["LAX", M.Imm], ["LDY", M.Abs], ["LDA", M.Abs], ["LDX", M.Abs], ["LAX", M.Abs]],
+    // 0xB0-0xBF
+    [["BCS", M.Rel], ["LDA", M.IndY], ["HLT", M.Imp], ["LAX", M.IndY], ["LDY", M.ZpX], ["LDA", M.ZpX], ["LDX", M.ZpY], ["LAX", M.ZpY], ["CLV", M.Imp], ["LDA", M.AbsY], ["TSX", M.Imp], ["LAS", M.AbsY], ["LDY", M.AbsX], ["LDA", M.AbsX], ["LDX", M.AbsY], ["LAX", M.AbsY]],
+    // 0xC0-0xCF
+    [["CPY", M.Imm], ["CMP", M.IndX], ["NOP", M.Imm], ["DCM", M.IndX], ["CPY", M.Zp], ["CMP", M.Zp], ["DEC", M.Zp], ["DCM", M.Zp], ["INY", M.Imp], ["CMP", M.Imm], ["DEX", M.Imp], ["AXS", M.Imm], ["CPY", M.Abs], ["CMP", M.Abs], ["DEC", M.Abs], ["DCM", M.Abs]],
+    // 0xD0-0xDF
+    [["BNE", M.Rel], ["CMP", M.IndY], ["HLT", M.Imp], ["DCM", M.IndY], ["NOP", M.ZpX], ["CMP", M.ZpX], ["DEC", M.ZpX], ["DCM", M.ZpX], ["CLD", M.Imp], ["CMP", M.AbsY], ["NOP", M.Imp], ["DCM", M.AbsY], ["NOP", M.AbsX], ["CMP", M.AbsX], ["DEC", M.AbsX], ["DCM", M.AbsX]],
+    // 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]],
+];
+const ILLEGAL_MAP = [
+    0x989C, 0x9C9C, 0x888C, 0x9C9C,
+    0x889C, 0x9C9C, 0x889C, 0x9C9C,
+    0x8A8D, 0xD88C, 0x8888, 0x888C,
+    0x888C, 0x9C9C, 0x888C, 0x9C9C,
+];
+function isIllegal(opcode) {
+    const row = ILLEGAL_MAP[opcode >> 4];
+    return ((row >> (opcode & 0x0F)) & 1) !== 0;
+}
+function canonical(mnemonic) {
+    switch (mnemonic) {
+        case "HLT": return "JAM";
+        case "ASO": return "SLO";
+        case "LSE": return "SRE";
+        case "DCM": return "DCP";
+        case "INS": return "ISC";
+        default: return mnemonic;
+    }
+}
+function buildOpcodeInventory() {
+    const entries = OPCODE_ROWS.flatMap((row, rowIndex) => row.map(([mnemonic, mode], columnIndex) => {
+        const opcode = (rowIndex << 4) | columnIndex;
+        return {
+            opcode,
+            mnemonic: canonical(mnemonic),
+            mode,
+            illegal: isIllegal(opcode),
+        };
+    }));
+    validateOpcodeInventory(entries);
+    return entries;
+}
+function validateOpcodeInventory(entries) {
+    if (entries.length !== 256) {
+        throw new Error(`Opcode inventory must contain 256 entries, found ${entries.length}`);
+    }
+    for (let opcode = 0; opcode < 256; opcode += 1) {
+        const entry = entries[opcode];
+        if (!entry || entry.opcode !== opcode) {
+            throw new Error(`Opcode inventory is not sorted at $${opcode.toString(16).padStart(2, "0")}`);
+        }
+    }
+}
+export function opcodeSize(mode) {
+    switch (mode) {
+        case M.Imp:
+        case M.Acc:
+            return 1;
+        case M.Imm:
+        case M.Zp:
+        case M.ZpX:
+        case M.ZpY:
+        case M.ZpS:
+        case M.Rel:
+        case M.IndX:
+        case M.IndY:
+            return 2;
+        case M.Abs:
+        case M.AbsX:
+        case M.AbsY:
+        case M.Ind:
+            return 3;
+    }
+}
+export const OPCODE_INVENTORY = Object.freeze(buildOpcodeInventory());
+export const OPCODES_BY_BYTE = OPCODE_INVENTORY;

package/doc/developer.md

@@ -124,9 +124,10 @@ Environment knobs: `RAG_EMBEDDINGS_DIR`, `RAG_BUILD_ON_START`, `RAG_REINDEX_INTE
 
 Tagging a release through the GitHub release UI triggers [`.github/workflows/release.yaml`](../.github/workflows/release.yaml), which publishes the npm package and then publishes the same version to the MCP Registry.
 
-- Required GitHub secret: `NPM_TOKEN`
+- npm publication now uses trusted publishing over GitHub OIDC rather than an `NPM_TOKEN` secret
+- One-time npm setup is required in the package settings for `c64bridge`: provider `GitHub Actions`, repository `chrisgleissner/c64bridge`, workflow `.github/workflows/release.yaml`, and allowed action `npm publish`
 - No dedicated MCP Registry secret is required for the GitHub-driven flow; the workflow uses `mcp-publisher login github-oidc`
-- The release workflow must grant `id-token: write` so GitHub Actions can mint the short-lived OIDC token used by `mcp-publisher`
+- The release workflow must grant `id-token: write` so GitHub Actions can mint the short-lived OIDC tokens used by both npm trusted publishing and `mcp-publisher`
 - Keep [`package.json`](../package.json) `mcpName` aligned with [`server.json`](../server.json) `name`
 - The root [`server.json`](../server.json) is the MCP Registry manifest; [`mcp/server.json`](../mcp/server.json) remains generated MCP interface output