c64bridge 0.9.0 → 0.9.1

package/dist/tools/disassembler.js

@@ -0,0 +1,478 @@
+/**
+ * 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).
+ */
+function entry(mnemonic, mode, illegal = false) {
+    return { mnemonic, mode, illegal };
+}
+// Canonicalization rules from disassembler_6502.cc:
+//   HLT -> JAM, ASO -> SLO, LSE -> SRE, DCM -> DCP, INS -> ISC
+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;
+    }
+}
+// 256-entry opcode table mirroring `opcode_templates` in disassembler_6502.cc.
+// `illegal` is taken from the bitmap `illegal_map` in the same reference.
+const OPCODES = (() => {
+    // Build the illegal-opcode bitmap from the reference file.
+    const ILLEGAL_MAP = [
+        0x989C, 0x9C9C, 0x888C, 0x9C9C,
+        0x889C, 0x9C9C, 0x889C, 0x9C9C,
+        0x8A8D, 0xD88C, 0x8888, 0x888C,
+        0x888C, 0x9C9C, 0x888C, 0x9C9C,
+    ];
+    const isIllegal = (op) => {
+        const row = ILLEGAL_MAP[op >> 4];
+        return ((row >> (op & 0x0F)) & 1) !== 0;
+    };
+    const t = new Array(256);
+    // Helper: fill one row of 16 entries by mnemonic/mode pairs.
+    const set = (op, mnemonic, mode) => {
+        t[op] = { mnemonic: canonical(mnemonic), mode, illegal: isIllegal(op) };
+    };
+    // 0x00-0x0F
+    set(0x00, "BRK", 0 /* Mode.Imp */);
+    set(0x01, "ORA", 12 /* Mode.IndX */);
+    set(0x02, "HLT", 0 /* Mode.Imp */);
+    set(0x03, "ASO", 12 /* Mode.IndX */);
+    set(0x04, "NOP", 3 /* Mode.Zp */);
+    set(0x05, "ORA", 3 /* Mode.Zp */);
+    set(0x06, "ASL", 3 /* Mode.Zp */);
+    set(0x07, "ASO", 3 /* Mode.Zp */);
+    set(0x08, "PHP", 0 /* Mode.Imp */);
+    set(0x09, "ORA", 2 /* Mode.Imm */);
+    set(0x0A, "ASL", 1 /* Mode.Acc */);
+    set(0x0B, "ANC", 2 /* Mode.Imm */);
+    set(0x0C, "NOP", 8 /* Mode.Abs */);
+    set(0x0D, "ORA", 8 /* Mode.Abs */);
+    set(0x0E, "ASL", 8 /* Mode.Abs */);
+    set(0x0F, "ASO", 8 /* Mode.Abs */);
+    // 0x10-0x1F
+    set(0x10, "BPL", 7 /* Mode.Rel */);
+    set(0x11, "ORA", 13 /* Mode.IndY */);
+    set(0x12, "HLT", 0 /* Mode.Imp */);
+    set(0x13, "ASO", 13 /* Mode.IndY */);
+    set(0x14, "NOP", 4 /* Mode.ZpX */);
+    set(0x15, "ORA", 4 /* Mode.ZpX */);
+    set(0x16, "ASL", 4 /* Mode.ZpX */);
+    set(0x17, "ASO", 4 /* Mode.ZpX */);
+    set(0x18, "CLC", 0 /* Mode.Imp */);
+    set(0x19, "ORA", 10 /* Mode.AbsY */);
+    set(0x1A, "NOP", 0 /* Mode.Imp */);
+    set(0x1B, "ASO", 10 /* Mode.AbsY */);
+    set(0x1C, "NOP", 9 /* Mode.AbsX */);
+    set(0x1D, "ORA", 9 /* Mode.AbsX */);
+    set(0x1E, "ASL", 9 /* Mode.AbsX */);
+    set(0x1F, "ASO", 9 /* Mode.AbsX */);
+    // 0x20-0x2F
+    set(0x20, "JSR", 8 /* Mode.Abs */);
+    set(0x21, "AND", 12 /* Mode.IndX */);
+    set(0x22, "HLT", 0 /* Mode.Imp */);
+    set(0x23, "RLA", 12 /* Mode.IndX */);
+    set(0x24, "BIT", 3 /* Mode.Zp */);
+    set(0x25, "AND", 3 /* Mode.Zp */);
+    set(0x26, "ROL", 3 /* Mode.Zp */);
+    set(0x27, "RLA", 3 /* Mode.Zp */);
+    set(0x28, "PLP", 0 /* Mode.Imp */);
+    set(0x29, "AND", 2 /* Mode.Imm */);
+    set(0x2A, "ROL", 1 /* Mode.Acc */);
+    set(0x2B, "ANC", 2 /* Mode.Imm */);
+    set(0x2C, "BIT", 8 /* Mode.Abs */);
+    set(0x2D, "AND", 8 /* Mode.Abs */);
+    set(0x2E, "ROL", 8 /* Mode.Abs */);
+    set(0x2F, "RLA", 8 /* Mode.Abs */);
+    // 0x30-0x3F
+    set(0x30, "BMI", 7 /* Mode.Rel */);
+    set(0x31, "AND", 13 /* Mode.IndY */);
+    set(0x32, "HLT", 0 /* Mode.Imp */);
+    set(0x33, "RLA", 13 /* Mode.IndY */);
+    set(0x34, "NOP", 4 /* Mode.ZpX */);
+    set(0x35, "AND", 4 /* Mode.ZpX */);
+    set(0x36, "ROL", 4 /* Mode.ZpX */);
+    set(0x37, "RLA", 4 /* Mode.ZpX */);
+    set(0x38, "SEC", 0 /* Mode.Imp */);
+    set(0x39, "AND", 10 /* Mode.AbsY */);
+    set(0x3A, "NOP", 0 /* Mode.Imp */);
+    set(0x3B, "RLA", 10 /* Mode.AbsY */);
+    set(0x3C, "NOP", 9 /* Mode.AbsX */);
+    set(0x3D, "AND", 9 /* Mode.AbsX */);
+    set(0x3E, "ROL", 9 /* Mode.AbsX */);
+    set(0x3F, "RLA", 9 /* Mode.AbsX */);
+    // 0x40-0x4F
+    set(0x40, "RTI", 0 /* Mode.Imp */);
+    set(0x41, "EOR", 12 /* Mode.IndX */);
+    set(0x42, "HLT", 0 /* Mode.Imp */);
+    set(0x43, "LSE", 12 /* Mode.IndX */);
+    set(0x44, "NOP", 3 /* Mode.Zp */);
+    set(0x45, "EOR", 3 /* Mode.Zp */);
+    set(0x46, "LSR", 3 /* Mode.Zp */);
+    set(0x47, "LSE", 3 /* Mode.Zp */);
+    set(0x48, "PHA", 0 /* Mode.Imp */);
+    set(0x49, "EOR", 2 /* Mode.Imm */);
+    set(0x4A, "LSR", 1 /* Mode.Acc */);
+    set(0x4B, "ALR", 2 /* Mode.Imm */);
+    set(0x4C, "JMP", 8 /* Mode.Abs */);
+    set(0x4D, "EOR", 8 /* Mode.Abs */);
+    set(0x4E, "LSR", 8 /* Mode.Abs */);
+    set(0x4F, "LSE", 8 /* Mode.Abs */);
+    // 0x50-0x5F
+    set(0x50, "BVC", 7 /* Mode.Rel */);
+    set(0x51, "EOR", 13 /* Mode.IndY */);
+    set(0x52, "HLT", 0 /* Mode.Imp */);
+    set(0x53, "LSE", 13 /* Mode.IndY */);
+    set(0x54, "NOP", 4 /* Mode.ZpX */);
+    set(0x55, "EOR", 4 /* Mode.ZpX */);
+    set(0x56, "LSR", 4 /* Mode.ZpX */);
+    set(0x57, "LSE", 4 /* Mode.ZpX */);
+    set(0x58, "CLI", 0 /* Mode.Imp */);
+    set(0x59, "EOR", 10 /* Mode.AbsY */);
+    set(0x5A, "NOP", 0 /* Mode.Imp */);
+    set(0x5B, "LSE", 10 /* Mode.AbsY */);
+    set(0x5C, "NOP", 9 /* Mode.AbsX */);
+    set(0x5D, "EOR", 9 /* Mode.AbsX */);
+    set(0x5E, "LSR", 9 /* Mode.AbsX */);
+    set(0x5F, "LSE", 9 /* Mode.AbsX */);
+    // 0x60-0x6F
+    set(0x60, "RTS", 0 /* Mode.Imp */);
+    set(0x61, "ADC", 12 /* Mode.IndX */);
+    set(0x62, "HLT", 0 /* Mode.Imp */);
+    set(0x63, "RRA", 12 /* Mode.IndX */);
+    set(0x64, "NOP", 3 /* Mode.Zp */);
+    set(0x65, "ADC", 3 /* Mode.Zp */);
+    set(0x66, "ROR", 3 /* Mode.Zp */);
+    set(0x67, "RRA", 3 /* Mode.Zp */);
+    set(0x68, "PLA", 0 /* Mode.Imp */);
+    set(0x69, "ADC", 2 /* Mode.Imm */);
+    set(0x6A, "ROR", 1 /* Mode.Acc */);
+    set(0x6B, "ARR", 2 /* Mode.Imm */);
+    set(0x6C, "JMP", 11 /* Mode.Ind */);
+    set(0x6D, "ADC", 8 /* Mode.Abs */);
+    set(0x6E, "ROR", 8 /* Mode.Abs */);
+    set(0x6F, "RRA", 8 /* Mode.Abs */);
+    // 0x70-0x7F
+    set(0x70, "BVS", 7 /* Mode.Rel */);
+    set(0x71, "ADC", 13 /* Mode.IndY */);
+    set(0x72, "HLT", 0 /* Mode.Imp */);
+    set(0x73, "RRA", 13 /* Mode.IndY */);
+    set(0x74, "NOP", 4 /* Mode.ZpX */);
+    set(0x75, "ADC", 4 /* Mode.ZpX */);
+    set(0x76, "ROR", 4 /* Mode.ZpX */);
+    set(0x77, "RRA", 4 /* Mode.ZpX */);
+    set(0x78, "SEI", 0 /* Mode.Imp */);
+    set(0x79, "ADC", 10 /* Mode.AbsY */);
+    set(0x7A, "NOP", 0 /* Mode.Imp */);
+    set(0x7B, "RRA", 10 /* Mode.AbsY */);
+    set(0x7C, "NOP", 9 /* Mode.AbsX */);
+    set(0x7D, "ADC", 9 /* Mode.AbsX */);
+    set(0x7E, "ROR", 9 /* Mode.AbsX */);
+    set(0x7F, "RRA", 9 /* Mode.AbsX */);
+    // 0x80-0x8F
+    set(0x80, "NOP", 2 /* Mode.Imm */);
+    set(0x81, "STA", 12 /* Mode.IndX */);
+    set(0x82, "NOP", 2 /* Mode.Imm */);
+    set(0x83, "SAX", 12 /* Mode.IndX */);
+    set(0x84, "STY", 3 /* Mode.Zp */);
+    set(0x85, "STA", 3 /* Mode.Zp */);
+    set(0x86, "STX", 3 /* Mode.Zp */);
+    set(0x87, "SAX", 3 /* Mode.Zp */);
+    set(0x88, "DEY", 0 /* Mode.Imp */);
+    set(0x89, "NOP", 2 /* Mode.Imm */);
+    set(0x8A, "TXA", 0 /* Mode.Imp */);
+    set(0x8B, "XAA", 2 /* Mode.Imm */);
+    set(0x8C, "STY", 8 /* Mode.Abs */);
+    set(0x8D, "STA", 8 /* Mode.Abs */);
+    set(0x8E, "STX", 8 /* Mode.Abs */);
+    set(0x8F, "SAX", 8 /* Mode.Abs */);
+    // 0x90-0x9F
+    set(0x90, "BCC", 7 /* Mode.Rel */);
+    set(0x91, "STA", 13 /* Mode.IndY */);
+    set(0x92, "HLT", 0 /* Mode.Imp */);
+    set(0x93, "AHX", 13 /* Mode.IndY */);
+    set(0x94, "STY", 4 /* Mode.ZpX */);
+    set(0x95, "STA", 4 /* Mode.ZpX */);
+    set(0x96, "STX", 5 /* Mode.ZpY */);
+    set(0x97, "SAX", 5 /* Mode.ZpY */);
+    set(0x98, "TYA", 0 /* Mode.Imp */);
+    set(0x99, "STA", 10 /* Mode.AbsY */);
+    set(0x9A, "TXS", 0 /* Mode.Imp */);
+    set(0x9B, "TAS", 10 /* Mode.AbsY */);
+    set(0x9C, "SHY", 9 /* Mode.AbsX */);
+    set(0x9D, "STA", 9 /* Mode.AbsX */);
+    set(0x9E, "SHX", 10 /* Mode.AbsY */);
+    set(0x9F, "AHX", 10 /* Mode.AbsY */);
+    // 0xA0-0xAF
+    set(0xA0, "LDY", 2 /* Mode.Imm */);
+    set(0xA1, "LDA", 12 /* Mode.IndX */);
+    set(0xA2, "LDX", 2 /* Mode.Imm */);
+    set(0xA3, "LAX", 12 /* Mode.IndX */);
+    set(0xA4, "LDY", 3 /* Mode.Zp */);
+    set(0xA5, "LDA", 3 /* Mode.Zp */);
+    set(0xA6, "LDX", 3 /* Mode.Zp */);
+    set(0xA7, "LAX", 3 /* Mode.Zp */);
+    set(0xA8, "TAY", 0 /* Mode.Imp */);
+    set(0xA9, "LDA", 2 /* Mode.Imm */);
+    set(0xAA, "TAX", 0 /* Mode.Imp */);
+    set(0xAB, "LAX", 2 /* Mode.Imm */);
+    set(0xAC, "LDY", 8 /* Mode.Abs */);
+    set(0xAD, "LDA", 8 /* Mode.Abs */);
+    set(0xAE, "LDX", 8 /* Mode.Abs */);
+    set(0xAF, "LAX", 8 /* Mode.Abs */);
+    // 0xB0-0xBF
+    set(0xB0, "BCS", 7 /* Mode.Rel */);
+    set(0xB1, "LDA", 13 /* Mode.IndY */);
+    set(0xB2, "HLT", 0 /* Mode.Imp */);
+    set(0xB3, "LAX", 13 /* Mode.IndY */);
+    set(0xB4, "LDY", 4 /* Mode.ZpX */);
+    set(0xB5, "LDA", 4 /* Mode.ZpX */);
+    set(0xB6, "LDX", 5 /* Mode.ZpY */);
+    set(0xB7, "LAX", 5 /* Mode.ZpY */);
+    set(0xB8, "CLV", 0 /* Mode.Imp */);
+    set(0xB9, "LDA", 10 /* Mode.AbsY */);
+    set(0xBA, "TSX", 0 /* Mode.Imp */);
+    set(0xBB, "LAS", 10 /* Mode.AbsY */);
+    set(0xBC, "LDY", 9 /* Mode.AbsX */);
+    set(0xBD, "LDA", 9 /* Mode.AbsX */);
+    set(0xBE, "LDX", 10 /* Mode.AbsY */);
+    set(0xBF, "LAX", 10 /* Mode.AbsY */);
+    // 0xC0-0xCF
+    set(0xC0, "CPY", 2 /* Mode.Imm */);
+    set(0xC1, "CMP", 12 /* Mode.IndX */);
+    set(0xC2, "NOP", 2 /* Mode.Imm */);
+    set(0xC3, "DCM", 12 /* Mode.IndX */);
+    set(0xC4, "CPY", 3 /* Mode.Zp */);
+    set(0xC5, "CMP", 3 /* Mode.Zp */);
+    set(0xC6, "DEC", 3 /* Mode.Zp */);
+    set(0xC7, "DCM", 3 /* Mode.Zp */);
+    set(0xC8, "INY", 0 /* Mode.Imp */);
+    set(0xC9, "CMP", 2 /* Mode.Imm */);
+    set(0xCA, "DEX", 0 /* Mode.Imp */);
+    set(0xCB, "AXS", 2 /* Mode.Imm */);
+    set(0xCC, "CPY", 8 /* Mode.Abs */);
+    set(0xCD, "CMP", 8 /* Mode.Abs */);
+    set(0xCE, "DEC", 8 /* Mode.Abs */);
+    set(0xCF, "DCM", 8 /* Mode.Abs */);
+    // 0xD0-0xDF
+    set(0xD0, "BNE", 7 /* Mode.Rel */);
+    set(0xD1, "CMP", 13 /* Mode.IndY */);
+    set(0xD2, "HLT", 0 /* Mode.Imp */);
+    set(0xD3, "DCM", 13 /* Mode.IndY */);
+    set(0xD4, "NOP", 4 /* Mode.ZpX */);
+    set(0xD5, "CMP", 4 /* Mode.ZpX */);
+    set(0xD6, "DEC", 4 /* Mode.ZpX */);
+    set(0xD7, "DCM", 4 /* Mode.ZpX */);
+    set(0xD8, "CLD", 0 /* Mode.Imp */);
+    set(0xD9, "CMP", 10 /* Mode.AbsY */);
+    set(0xDA, "NOP", 0 /* Mode.Imp */);
+    set(0xDB, "DCM", 10 /* Mode.AbsY */);
+    set(0xDC, "NOP", 9 /* Mode.AbsX */);
+    set(0xDD, "CMP", 9 /* Mode.AbsX */);
+    set(0xDE, "DEC", 9 /* Mode.AbsX */);
+    set(0xDF, "DCM", 9 /* Mode.AbsX */);
+    // 0xE0-0xEF
+    set(0xE0, "CPX", 2 /* Mode.Imm */);
+    set(0xE1, "SBC", 12 /* Mode.IndX */);
+    set(0xE2, "NOP", 2 /* Mode.Imm */);
+    set(0xE3, "INS", 12 /* Mode.IndX */);
+    set(0xE4, "CPX", 3 /* Mode.Zp */);
+    set(0xE5, "SBC", 3 /* Mode.Zp */);
+    set(0xE6, "INC", 3 /* Mode.Zp */);
+    set(0xE7, "INS", 3 /* Mode.Zp */);
+    set(0xE8, "INX", 0 /* Mode.Imp */);
+    set(0xE9, "SBC", 2 /* Mode.Imm */);
+    set(0xEA, "NOP", 0 /* Mode.Imp */);
+    set(0xEB, "SBC", 2 /* Mode.Imm */);
+    set(0xEC, "CPX", 8 /* Mode.Abs */);
+    set(0xED, "SBC", 8 /* Mode.Abs */);
+    set(0xEE, "INC", 8 /* Mode.Abs */);
+    set(0xEF, "INS", 8 /* Mode.Abs */);
+    // 0xF0-0xFF
+    set(0xF0, "BEQ", 7 /* Mode.Rel */);
+    set(0xF1, "SBC", 13 /* Mode.IndY */);
+    set(0xF2, "HLT", 0 /* Mode.Imp */);
+    set(0xF3, "INS", 13 /* Mode.IndY */);
+    set(0xF4, "NOP", 6 /* Mode.ZpS */);
+    set(0xF5, "SBC", 4 /* Mode.ZpX */);
+    set(0xF6, "INC", 4 /* Mode.ZpX */);
+    set(0xF7, "INS", 4 /* Mode.ZpX */);
+    set(0xF8, "SED", 0 /* Mode.Imp */);
+    set(0xF9, "SBC", 10 /* Mode.AbsY */);
+    set(0xFA, "NOP", 0 /* Mode.Imp */);
+    set(0xFB, "INS", 10 /* Mode.AbsY */);
+    set(0xFC, "NOP", 9 /* Mode.AbsX */);
+    set(0xFD, "SBC", 9 /* Mode.AbsX */);
+    set(0xFE, "INC", 9 /* Mode.AbsX */);
+    set(0xFF, "INS", 9 /* Mode.AbsX */);
+    return t;
+})();
+function modeSize(mode) {
+    switch (mode) {
+        case 0 /* Mode.Imp */:
+        case 1 /* Mode.Acc */:
+            return 1;
+        case 2 /* Mode.Imm */:
+        case 3 /* Mode.Zp */:
+        case 4 /* Mode.ZpX */:
+        case 5 /* Mode.ZpY */:
+        case 6 /* Mode.ZpS */:
+        case 7 /* Mode.Rel */:
+        case 12 /* Mode.IndX */:
+        case 13 /* Mode.IndY */:
+            return 2;
+        case 8 /* Mode.Abs */:
+        case 9 /* Mode.AbsX */:
+        case 10 /* Mode.AbsY */:
+        case 11 /* Mode.Ind */:
+            return 3;
+    }
+}
+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 0 /* Mode.Imp */:
+            return "";
+        case 1 /* Mode.Acc */:
+            return "A";
+        case 2 /* Mode.Imm */:
+            return `#$${hex2(bytes[offset + 1] ?? 0)}`;
+        case 3 /* Mode.Zp */:
+            return `$${hex2(bytes[offset + 1] ?? 0)}`;
+        case 4 /* Mode.ZpX */:
+            return `$${hex2(bytes[offset + 1] ?? 0)},X`;
+        case 5 /* Mode.ZpY */:
+            return `$${hex2(bytes[offset + 1] ?? 0)},Y`;
+        case 6 /* Mode.ZpS */:
+            return `$${hex2(bytes[offset + 1] ?? 0)},S`;
+        case 7 /* 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 8 /* Mode.Abs */: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return labelOrHex4(addr, symbols);
+        }
+        case 9 /* 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 10 /* 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 11 /* Mode.Ind */: {
+            const lo = bytes[offset + 1] ?? 0;
+            const hi = bytes[offset + 2] ?? 0;
+            const addr = lo | (hi << 8);
+            return `($${hex4(addr)})`;
+        }
+        case 12 /* Mode.IndX */:
+            return `($${hex2(bytes[offset + 1] ?? 0)},X)`;
+        case 13 /* 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++) {
+            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) };
+}