@audiofab-io/fv1-core 0.1.0

package/dist/simulator/FV1Simulator.js

@@ -0,0 +1,1081 @@
+/**
+ * FV-1 DSP Simulator
+ *
+ * Simulates the Spin Semiconductor FV-1 DSP chip.
+ * This class is designed to be platform-agnostic (Node.js or Browser/AudioWorklet).
+ */
+import { FV1Assembler } from '../assembler/FV1Assembler.js';
+export class FV1Simulator {
+    // Register aliases (Getters/Setters)
+    // 0-7: Parameters
+    // These are now handled by updateStateRegisters for debugger view
+    // 8-13: Internal State accumulators (aliased as registers for the debugger)
+    // These are now handled by updateStateRegisters for debugger view
+    constructor() {
+        // Constants
+        // Capabilities (Configurable)
+        this.delaySize = 32768;
+        this.delayMask = 32767; // For efficient circular buffer
+        this.regCount = 32;
+        this.progSize = 128;
+        // --- Float-based LFO state (from Expert Sleepers C port) ---
+        this.sin0 = 0;
+        this.cos0 = 0;
+        this.sin1 = 0;
+        this.cos1 = 0;
+        this.rmp0 = 0;
+        this.rmp1 = 0;
+        this.sin0_rate = 0;
+        this.sin0_range = 0;
+        this.sin1_rate = 0;
+        this.sin1_range = 0;
+        this.rmp0_rate = 0;
+        this.rmp0_range = 0;
+        this.rmp1_rate = 0;
+        this.rmp1_range = 0;
+        this.acc = 0;
+        this.pacc = 0;
+        this.lr = 0; // Last Read register
+        this.lfo = 0; // Internal LFO fregister (for CHO)
+        this.delayPointer = 0; // Circular buffer pointer
+        this.firstRun = true;
+        this.pc = 0; // Program Counter
+        this.breakpoints = new Set();
+        // Symbol metadata (optional, for debugging)
+        this.symbols = [];
+        this.memories = [];
+        this.fv1AsmMemBug = false;
+        // --- Trace Logging ---
+        this.traceEnabled = false;
+        this.traceWriter = null; // Streaming callback
+        this.cycleCount = 0;
+        this.traceCycle = 0;
+        this.traceMaxCycles = 0; // 0 = unlimited
+        this.traceRowCount = 0;
+        this.traceDelayAddr = -1; // computed physical address in delay RAM
+        this.traceDelayOffset = -1; // raw offset from instruction (identifies MEM block)
+        this.traceDelayOp = ''; // 'R' for read, 'W' for write
+        this.traceDelayValue = 0; // value read/written
+        this.traceInstructionPC = -1; // PC of currently executing instruction
+        this.currentReadOffsets = new Set(); // Tracks read offsets in current sample cycle
+        this.traceOnComplete = null;
+        this.delayRam = new Float32Array(this.delaySize);
+        this.registers = new Float32Array(32 + this.regCount);
+        this.program = new Uint32Array(this.progSize);
+    }
+    /**
+     * Configures simulator hardware limits.
+     */
+    setCapabilities(delaySize, regCount, progSize) {
+        this.delaySize = delaySize;
+        this.delayMask = delaySize - 1; // Assuming power of 2 for now, but modulo is fallback
+        this.regCount = regCount; // Number of user registers
+        this.progSize = progSize;
+        // Reallocate if needed
+        this.delayRam = new Float32Array(this.delaySize);
+        this.registers = new Float32Array(32 + this.regCount); // 32 system + N user registers
+        this.program = new Uint32Array(this.progSize);
+        this.reset();
+    }
+    getDelayPointer() {
+        return this.delayPointer;
+    }
+    getDelaySize() {
+        return this.delaySize;
+    }
+    /**
+     * Loads the machine code into the simulator.
+     * @param code Array of 32-bit integers representing the assembled program.
+     */
+    loadProgram(code) {
+        if (code.length > this.progSize) {
+            console.warn(`Program size (${code.length}) exceeds max size (${this.progSize}). Truncating.`);
+        }
+        this.program.fill(0);
+        this.program.set(code.slice(0, this.progSize));
+        this.reset();
+    }
+    /**
+     * Resets the simulator state (clears memory, registers, accumulator).
+     */
+    reset() {
+        this.delayRam.fill(0);
+        this.registers.fill(0);
+        this.acc = 0;
+        this.pacc = 0;
+        this.lr = 0;
+        this.lfo = 0;
+        this.pc = 0;
+        this.delayPointer = 0;
+        this.firstRun = true;
+        this.sin0 = 0;
+        this.sin1 = 0;
+        // Peak amplitude from Java SinLFO.java initialized to -0x7fff00 mapped to float (-1.0)
+        // BUT wait, in C the initialization is not explicit, we can just use 1.0 or -1.0
+        // SpinCAD sets cos to -0x7fff00l which is approx -1.0
+        this.cos0 = -1.0;
+        this.cos1 = -1.0;
+        this.rmp0 = 0;
+        this.rmp1 = 0;
+        this.sin0_rate = 0;
+        this.sin0_range = 0;
+        this.sin1_rate = 0;
+        this.sin1_range = 0;
+        this.rmp0_rate = 0;
+        this.rmp0_range = 0;
+        this.rmp1_rate = 0;
+        this.rmp1_range = 0;
+        // Default POT values to 0.5
+        this.registers[16] = 0.5;
+        this.registers[17] = 0.5;
+        this.registers[18] = 0.5;
+    }
+    /**
+     * Set breakpoints at specific instruction addresses.
+     * @param addresses Set of addresses to break at.
+     */
+    setBreakpoints(addresses) {
+        this.breakpoints = addresses;
+    }
+    /**
+     * Set symbol and memory metadata for expression evaluation.
+     */
+    setSymbols(symbols, memories, fv1AsmMemBug = false) {
+        this.symbols = symbols;
+        this.memories = memories;
+        this.fv1AsmMemBug = fv1AsmMemBug;
+    }
+    /**
+     * Process a block of audio samples.
+     * Useful for real-time audio processing in AudioWorklets.
+     */
+    processBlock(inputL, inputR, outputL, outputR, pot0, pot1, pot2) {
+        const len = inputL.length;
+        for (let i = 0; i < len; i++) {
+            const [outL, outR] = this.step(inputL[i], inputR[i], pot0, pot1, pot2);
+            outputL[i] = outL;
+            outputR[i] = outR;
+        }
+    }
+    /**
+     * Process a single sample frame.
+     * Executes instructions until the end of the program or a breakpoint is hit.
+     * @param skipCurrentBreakpoint If true, will not break on the instruction at the current PC.
+     * @returns [outL, outR, breakpointHit]
+     */
+    step(inL, inR, pot0, pot1, pot2, skipCurrentBreakpoint = false) {
+        // Only begin a new frame if we are at PC 0 (either start or after wrap around)
+        if (this.pc === 0) {
+            this.beginFrame(inL, inR, pot0, pot1, pot2);
+        }
+        let firstInstruction = true;
+        while (this.pc < this.progSize) {
+            if (this.breakpoints.has(this.pc)) {
+                if (!firstInstruction || !skipCurrentBreakpoint) {
+                    return [...this.getOutputs(), true];
+                }
+            }
+            this.stepInstruction();
+            firstInstruction = false;
+        }
+        return [...this.endFrame(), false];
+    }
+    getOutputs() {
+        return [this.registers[22], this.registers[23]];
+    }
+    beginFrame(inL = 0, inR = 0, pot0 = 0, pot1 = 0, pot2 = 0) {
+        this.cycleCount++;
+        this.currentReadOffsets.clear();
+        // Saturate inputs (ADC is -1.0 to 0.999..., POT is 0 to 0.999...)
+        // POT has 10-bit resolution (1024 levels)
+        const sat = (v) => Math.max(-1.0, Math.min(FV1Simulator.MAX_ACC, v));
+        const satPot = (v) => {
+            const quantized = Math.floor(Math.max(0, Math.min(0.9999999, v)) * 1024) / 1024;
+            return quantized;
+        };
+        // Execute Program Setup
+        this.acc = 0; // Accumulator is cleared at start of run
+        this.lr = 0; // LR is transient
+        this.pacc = 0;
+        this.pc = 0;
+        // Map inputs to registers (Standard FV-1 mapping)
+        this.registers[20] = sat(inL);
+        this.registers[21] = sat(inR);
+        this.registers[16] = satPot(pot0);
+        this.registers[17] = satPot(pot1);
+        this.registers[18] = satPot(pot2);
+        this.updateStateRegisters();
+    }
+    endFrame() {
+        this.pc = 0;
+        this.firstRun = false;
+        this.updateLFOs();
+        this.updateStateRegisters();
+        this.advanceTraceCycle();
+        // Advance Delay Pointer (Circular Buffer)
+        this.delayPointer = (this.delayPointer - 1 + this.delaySize) % this.delaySize;
+        // Outputs (DACL = REG22, DACR = REG23)
+        return [this.registers[22], this.registers[23]];
+    }
+    /**
+     * Executes a single instruction at the current PC.
+     * @returns The next PC address.
+     */
+    stepInstruction() {
+        if (this.pc >= this.progSize)
+            return this.pc;
+        const inst = this.program[this.pc];
+        const opcode = inst & 0x1F;
+        const preOpAcc = this.acc;
+        // Reset per-instruction trace state
+        this.traceDelayAddr = -1;
+        this.traceDelayOffset = -1;
+        this.traceDelayOp = '';
+        this.traceDelayValue = 0;
+        this.traceInstructionPC = this.pc;
+        const skip = this.executeInstruction(inst);
+        // Trace log AFTER instruction executes so ACC reflects the result
+        if (this.traceEnabled) {
+            this.logTrace(this.traceInstructionPC, opcode, inst, preOpAcc);
+        }
+        if (opcode !== 0x11) { // Not SKP
+            this.pacc = preOpAcc;
+        }
+        this.pc += 1 + skip;
+        return this.pc;
+    }
+    executeInstruction(inst) {
+        const opcode = inst & 0x1F; // Bottom 5 bits for opcode
+        let skip = 0;
+        switch (opcode) {
+            case 0x00: // RDA (Read Delay Accumulate)
+                this.opRDA(inst);
+                break;
+            case 0x01: // RMPA (Read Memory Pointer Accumulate)
+                this.opRMPA(inst);
+                break;
+            case 0x02: // WRA (Write Delay Accumulate)
+                this.opWRA(inst);
+                break;
+            case 0x03: // WRAP (Write Delay Accumulate & Pointer)
+                this.opWRAP(inst);
+                break;
+            case 0x04: // RDAX (Read Register Accumulate)
+                this.opRDAX(inst);
+                break;
+            case 0x05: // RDFX (Read Register Filter)
+                this.opRDFX(inst);
+                break;
+            case 0x06: // WRAX (Write Register Accumulate)
+                this.opWRAX(inst);
+                break;
+            case 0x07: // WRHX (Write Register High)
+                this.opWRHX(inst);
+                break;
+            case 0x08: // WRLX (Write Register Low)
+                this.opWRLX(inst);
+                break;
+            case 0x09: // MAXX
+                this.opMAXX(inst);
+                break;
+            case 0x0A: // MULX
+                this.opMULX(inst);
+                break;
+            case 0x0B: // LOG
+                this.opLOG(inst);
+                break;
+            case 0x0C: // EXP
+                this.opEXP(inst);
+                break;
+            case 0x0D: // SOF
+                this.opSOF(inst);
+                break;
+            case 0x0E: // AND
+                this.opAND(inst);
+                break;
+            case 0x0F: // OR
+                this.opOR(inst);
+                break;
+            case 0x10: // XOR
+                this.opXOR(inst);
+                break;
+            case 0x11: // SKP
+                skip = this.opSKP(inst);
+                break;
+            case 0x12: // WLDS / WLDR
+                // Check bit 30 to distinguish WLDS (0) and WLDR (1)
+                if ((inst >>> 30) & 1) {
+                    this.opWLDR(inst);
+                }
+                else {
+                    this.opWLDS(inst);
+                }
+                break;
+            case 0x13: // JAM
+                this.opJAM(inst);
+                break;
+            case 0x14: // CHO
+                this.opCHO(inst);
+                break;
+            default:
+                // console.warn(`Unknown opcode: ${opcode.toString(16)}`);
+                break;
+        }
+        return skip;
+    }
+    // --- Opcode Implementations ---
+    opRDA(inst) {
+        // ... (existing comments)
+        const addr = (inst >>> 5) & 0x7FFF;
+        const coeff = this.decodeS1_9((inst >>> 21) & 0x7FF);
+        // Address is relative to current delay pointer in circular buffer
+        const readAddr = (this.delayPointer + addr) & this.delayMask;
+        const val = this.delayRam[readAddr];
+        this.traceDelayAddr = readAddr;
+        this.traceDelayOffset = addr;
+        this.traceDelayOp = 'R';
+        this.traceDelayValue = val;
+        this.currentReadOffsets.add(addr);
+        this.lr = val;
+        this.acc += val * coeff;
+        this.acc = this.saturate(this.acc);
+    }
+    opWRA(inst) {
+        // WRA addr, coeff
+        // Delay[addr] = ACC; ACC = ACC * coeff
+        // Encoding: CCCCCCCCCCCAAAAAAAAAAAAAAAA00010
+        const addr = (inst >>> 5) & 0x7FFF;
+        const coeff = this.decodeS1_9((inst >>> 21) & 0x7FF);
+        const writeAddr = (this.delayPointer + addr) & this.delayMask;
+        this.traceDelayAddr = writeAddr;
+        this.traceDelayOffset = addr;
+        this.traceDelayOp = 'W';
+        this.traceDelayValue = this.acc;
+        this.delayRam[writeAddr] = this.acc;
+        this.acc *= coeff;
+        this.acc = this.saturate(this.acc);
+    }
+    opWRAP(inst) {
+        // WRAP addr, coeff
+        // Delay[addr] = ACC; ACC = ACC * coeff + LR
+        // Note: Pointer decrement happens at end of step, not here.
+        // Encoding: CCCCCCCCCCCAAAAAAAAAAAAAAAA00011
+        const addr = (inst >>> 5) & 0x7FFF;
+        const coeff = this.decodeS1_9((inst >>> 21) & 0x7FF);
+        const writeAddr = (this.delayPointer + addr) & this.delayMask;
+        this.traceDelayAddr = writeAddr;
+        this.traceDelayOffset = addr;
+        this.traceDelayOp = 'W';
+        this.traceDelayValue = this.acc;
+        this.delayRam[writeAddr] = this.acc;
+        // ACC = ACC * coeff + LR
+        this.acc = this.acc * coeff + this.lr;
+        this.acc = this.saturate(this.acc);
+    }
+    opRDAX(inst) {
+        // RDAX reg, coeff
+        // ACC = ACC + (Reg[reg] * coeff)
+        // Encoding: CCCCCCCCCCCCCCCC00000AAAAAA00100
+        const reg = (inst >>> 5) & 0x3F;
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        const val = this.registers[reg];
+        this.acc += val * coeff;
+        this.acc = this.saturate(this.acc);
+    }
+    opWRAX(inst) {
+        // WRAX reg, coeff
+        // Reg[reg] = ACC; ACC = ACC * coeff
+        // Encoding: CCCCCCCCCCCCCCCC00000AAAAAA00110
+        const reg = (inst >>> 5) & 0x3F;
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        this.registers[reg] = this.acc;
+        this.acc *= coeff;
+        this.acc = this.saturate(this.acc);
+    }
+    opSOF(inst) {
+        // SOF c, d
+        // ACC = ACC * c + d
+        // Encoding: CCCCCCCCCCCCCCCCDDDDDDDDDDD01101
+        const d = this.decodeS_10((inst >>> 5) & 0x7FF);
+        const c = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        this.acc = this.acc * c + d;
+        this.acc = this.saturate(this.acc);
+    }
+    opRMPA(inst) {
+        // RMPA coeff
+        // Read memory pointer. ADDR_PTR is mapped to REG24.
+        // Encoding: CCCCCCCCCCC000000000001100000001 (or similar, coeff is top)
+        const coeff = this.decodeS1_9((inst >>> 21) & 0x7FF);
+        const ptr = Math.floor(this.registers[24] * this.delaySize);
+        const readAddr = (this.delayPointer + ptr) % this.delaySize;
+        const val = this.delayRam[readAddr];
+        this.traceDelayAddr = readAddr;
+        this.traceDelayOffset = ptr;
+        this.traceDelayOp = 'R';
+        this.traceDelayValue = val;
+        this.currentReadOffsets.add(ptr);
+        this.lr = val;
+        this.acc += val * coeff;
+        this.acc = this.saturate(this.acc);
+    }
+    opMULX(inst) {
+        // Encoding: 000000000000000000000AAAAAA01010
+        const reg = (inst >>> 5) & 0x3F;
+        this.acc = this.acc * this.registers[reg];
+        this.acc = this.saturate(this.acc);
+    }
+    opLOG(inst) {
+        // ACC = log2(|ACC|) * coeff + d
+        // Encoding: CCCCCCCCCCCCCCCCDDDDDDDDDDD01011
+        const d = this.decodeS4_6((inst >>> 5) & 0x7FF);
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        const val = Math.abs(this.acc);
+        let logVal;
+        if (val > 1.52587890625e-5) { // 2^-16, approx 96dB limit
+            logVal = Math.log2(val);
+        }
+        else {
+            logVal = -16.0;
+        }
+        // Result is in S4.19 format, so we divide by 16 to keep it in our S.23 float space
+        this.acc = (logVal * coeff + d) / 16.0;
+        this.acc = this.saturate(this.acc);
+    }
+    opEXP(inst) {
+        // ACC = 2^ACC
+        // Encoding: CCCCCCCCCCCCCCCCDDDDDDDDDDD01100
+        const d = this.decodeS_10((inst >>> 5) & 0x7FF);
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        const valS419 = this.acc * 16.0;
+        // Result is linear S.23, which naturally fits our -1..1 float range
+        this.acc = Math.pow(2, valS419) * coeff + d;
+        this.acc = this.saturate(this.acc);
+    }
+    opRDFX(inst) {
+        // RDFX reg, coeff
+        // ACC = (REG[reg] - ACC) * coeff + REG[reg]
+        // Encoding: CCCCCCCCCCCCCCCC00000AAAAAA00101
+        const reg = (inst >>> 5) & 0x3F;
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        const rx = this.registers[reg];
+        this.acc = (this.acc - rx) * coeff + rx;
+        this.acc = this.saturate(this.acc);
+    }
+    opMAXX(inst) {
+        // Encoding: CCCCCCCCCCCCCCCC00000AAAAAA01001
+        const reg = (inst >>> 5) & 0x3F;
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        const a = Math.abs(this.acc);
+        const b = Math.abs(this.registers[reg] * coeff);
+        // MAXX result is always the magnitude (absolute value)
+        this.acc = Math.max(a, b);
+        this.acc = this.saturate(this.acc);
+    }
+    opSKP(inst) {
+        // SKP condition, n
+        // Encoding: CCCCCNNNNNN000000000000000010001
+        const n = (inst >>> 21) & 0x3F;
+        const flags = inst & 0xF8000000;
+        let conditionMet = false;
+        // Flags: RUN=0x80000000, ZRC=0x40000000, ZRO=0x20000000, GEZ=0x10000000, NEG=0x08000000
+        if ((flags & 0x08000000) && this.acc < 0)
+            conditionMet = true; // NEG
+        if ((flags & 0x10000000) && this.acc >= 0)
+            conditionMet = true; // GEZ
+        if ((flags & 0x20000000) && this.acc === 0)
+            conditionMet = true; // ZRO
+        // ZRC (Zero Crossing) requires previous acc
+        if ((flags & 0x40000000) && (this.acc * this.pacc < 0))
+            conditionMet = true;
+        // RUN flag: Skip if NOT first run
+        if ((flags & 0x80000000) && !this.firstRun)
+            conditionMet = true;
+        return conditionMet ? n : 0;
+    }
+    opWRLX(inst) {
+        // WRLX reg, coeff
+        // Reg[reg] = ACC; ACC = (PACC - ACC) * coeff + PACC
+        // Encoding: CCCCCCCCCCCCCCCC00000AAAAAA01000
+        const reg = (inst >>> 5) & 0x3F;
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        this.registers[reg] = this.acc;
+        this.acc = (this.pacc - this.acc) * coeff + this.pacc;
+        this.acc = this.saturate(this.acc);
+    }
+    opWRHX(inst) {
+        // WRHX reg, coeff
+        // Reg[reg] = ACC; ACC = PACC + ACC * coeff
+        // Encoding: CCCCCCCCCCCCCCCC00000AAAAAA00111
+        const reg = (inst >>> 5) & 0x3F;
+        const coeff = this.decodeS1_14((inst >>> 16) & 0xFFFF);
+        this.registers[reg] = this.acc;
+        this.acc = this.pacc + this.acc * coeff;
+        this.acc = this.saturate(this.acc);
+    }
+    opAND(inst) {
+        // AND mask
+        // Encoding: MMMMMMMMMMMMMMMMMMMMMMMM00001110
+        const mask = (inst >>> 8) & 0xFFFFFF;
+        // Convert ACC to 24-bit int, apply mask, convert back
+        let iAcc = Math.floor(this.acc * 8388608.0); // 2^23
+        iAcc &= mask;
+        this.acc = iAcc / 8388608.0;
+    }
+    opOR(inst) {
+        // OR mask
+        // Encoding: MMMMMMMMMMMMMMMMMMMMMMMM00001111
+        const mask = (inst >>> 8) & 0xFFFFFF;
+        let iAcc = Math.floor(this.acc * 8388608.0);
+        iAcc |= mask;
+        this.acc = iAcc / 8388608.0;
+    }
+    opXOR(inst) {
+        // XOR mask
+        // Encoding: MMMMMMMMMMMMMMMMMMMMMMMM00010000
+        const mask = (inst >>> 8) & 0xFFFFFF;
+        let iAcc = Math.floor(this.acc * 8388608.0);
+        iAcc ^= mask;
+        this.acc = iAcc / 8388608.0;
+    }
+    opJAM(inst) {
+        // JAM lfo
+        // Encoding: 0000000000000000000000001N010011
+        const lfo = (inst >>> 6) & 0x3; // 0=RMP0, 1=RMP1
+        if (lfo === 0)
+            this.rmp0 = 0;
+        else if (lfo === 1)
+            this.rmp1 = 0;
+    }
+    opWLDS(inst) {
+        // WLDS lfo, freq, amp
+        const lfoSelect = (inst >>> 29) & 0x1;
+        const freqRaw = (inst >>> 20) & 0x1FF;
+        const ampRaw = (inst >>> 5) & 0x7FFF;
+        // Freq is an unsigned 9-bit value (0 to 511), amp is unsigned 15-bit (0 to 32767).
+        // The FV-1 hardware uses power-of-2 fixed-point arithmetic (bit shifts),
+        // so amplitude is divided by 2^15=32768, not 32767. Using 32767 causes the
+        // computed delay address range to slightly exceed memory block boundaries.
+        const f = freqRaw / 512.0;
+        const a = ampRaw / 32768.0;
+        if (lfoSelect === 0) {
+            this.sin0_rate = f;
+            this.sin0_range = a;
+            this.registers[0] = f; // SIN0_RATE (reg0)
+            this.registers[1] = a; // SIN0_RANGE (reg1)
+            this.cos0 = -1.0;
+            this.sin0 = 0.0;
+        }
+        else {
+            this.sin1_rate = f;
+            this.sin1_range = a;
+            this.registers[2] = f; // SIN1_RATE (reg2)
+            this.registers[3] = a; // SIN1_RANGE (reg3)
+            this.cos1 = -1.0;
+            this.sin1 = 0.0;
+        }
+    }
+    opWLDR(inst) {
+        // WLDR lfo, freq, amp
+        // Encoding: 01NFFFFFFFFFFFFFFFF000000AA10010
+        const lfoSelect = (inst >>> 29) & 0x1; // 0=RMP0, 1=RMP1
+        // Freq is signed 16-bit
+        let freq = (inst >>> 13) & 0xFFFF;
+        if (freq & 0x8000)
+            freq -= 65536;
+        // Amp is a 2-bit code
+        const ampCode = (inst >>> 5) & 0x3;
+        const amp = 4096 >> ampCode; // 0->4096, 1->2048, 2->1024, 3->512
+        // C logic: rate = f/16384.0, range = a/8192.0
+        const f_val = freq / 16384.0;
+        const a_val = amp / 8192.0;
+        if (lfoSelect === 0) {
+            this.rmp0_rate = f_val;
+            this.rmp0_range = a_val;
+            this.registers[4] = f_val; // RMP0_RATE (reg4)
+            this.registers[5] = a_val; // RMP0_RANGE (reg5)
+            this.rmp0 = 0.0;
+        }
+        else {
+            this.rmp1_rate = f_val;
+            this.rmp1_range = a_val;
+            this.registers[6] = f_val; // RMP1_RATE (reg6)
+            this.registers[7] = a_val; // RMP1_RANGE (reg7)
+            this.rmp1 = 0.0;
+        }
+    }
+    getLfoVal(flags, lfoSelect) {
+        if (lfoSelect === 0) {
+            return (flags & 1) ? this.cos0 : this.sin0;
+        }
+        else if (lfoSelect === 1) {
+            return (flags & 1) ? this.cos1 : this.sin1;
+        }
+        else if (lfoSelect === 2) {
+            return this.rmp0;
+        }
+        else {
+            return this.rmp1;
+        }
+    }
+    getLfoRange(lfoSelect) {
+        if (lfoSelect === 0)
+            return this.sin0_range;
+        if (lfoSelect === 1)
+            return this.sin1_range;
+        if (lfoSelect === 2)
+            return this.rmp0_range;
+        return this.rmp1_range;
+    }
+    opCHO(inst) {
+        const mode = (inst >>> 30) & 0x3;
+        if (mode === 0) {
+            this.opCHO_RDA(inst);
+        }
+        else if (mode === 2) {
+            this.opCHO_SOF(inst);
+        }
+        else if (mode === 3) {
+            this.opCHO_RDAL(inst);
+        }
+    }
+    opCHO_RDA(inst) {
+        const flags = (inst >>> 24) & 0x3F;
+        const lfoSelect = (inst >>> 21) & 0x3;
+        const offset = (inst >>> 5) & 0x7FFF;
+        const lfoIn = this.getLfoVal(flags, lfoSelect);
+        let range = this.getLfoRange(lfoSelect);
+        range *= 8192.0;
+        if (flags & 2) { // cho_reg
+            this.lfo = lfoIn;
+        }
+        let v = this.lfo;
+        if (flags & 16) { // cho_rptr2
+            v += 0.5;
+            if (v >= 1.0)
+                v -= 1.0;
+        }
+        if (flags & 8) { // cho_compa
+            v = -v;
+        }
+        let index;
+        let c;
+        if (flags & 32) { // cho_na
+            index = offset;
+            c = Math.min(v, 1.0 - v);
+            c = Math.max(0.0, Math.min(1.0, 4.0 * c - 0.5));
+        }
+        else {
+            const lfoVal = v * range;
+            const lfoInteger = Math.trunc(lfoVal);
+            c = lfoVal - lfoInteger;
+            index = lfoInteger + offset;
+        }
+        const readAddr = (this.delayPointer + index) & this.delayMask;
+        this.lr = this.delayRam[readAddr];
+        this.traceDelayAddr = readAddr;
+        this.traceDelayOffset = index;
+        this.traceDelayOp = 'R';
+        this.traceDelayValue = this.lr;
+        this.currentReadOffsets.add(index);
+        if (flags & 4) { // cho_compc
+            c = 1.0 - c;
+        }
+        this.acc += this.lr * c;
+        this.acc = this.saturate(this.acc);
+    }
+    opCHO_SOF(inst) {
+        const flags = (inst >>> 24) & 0x3F;
+        const lfoSelect = (inst >>> 21) & 0x3;
+        const coeffRaw = (inst >>> 5) & 0xFFFF;
+        const coeff = this.decodeS_15(coeffRaw);
+        const lfoIn = this.getLfoVal(flags, lfoSelect);
+        const range = this.getLfoRange(lfoSelect);
+        if (flags & 2) { // cho_reg
+            this.lfo = lfoIn;
+        }
+        let v = this.lfo;
+        if (flags & 32) { // cho_na
+            v = Math.min(v, 1.0 - v);
+            v = Math.max(0.0, Math.min(1.0, 4.0 * v - 0.5));
+        }
+        else {
+            v *= range;
+        }
+        if (flags & 4) { // cho_compc
+            v = 1.0 - v;
+        }
+        this.acc = v * this.acc + coeff;
+        this.acc = this.saturate(this.acc);
+    }
+    opCHO_RDAL(inst) {
+        const flags = (inst >>> 24) & 0x3F;
+        const lfoSelect = (inst >>> 21) & 0x3;
+        const lfoIn = this.getLfoVal(flags, lfoSelect);
+        this.acc = lfoIn;
+        this.acc = this.saturate(this.acc);
+    }
+    // --- Debugging / State Access ---
+    getPC() {
+        return this.pc;
+    }
+    getProgSize() {
+        return this.progSize;
+    }
+    setPC(pc) {
+        this.pc = Math.max(0, Math.min(this.progSize - 1, pc));
+    }
+    setAcc(val) {
+        this.acc = this.saturate(val);
+    }
+    setPacc(val) {
+        this.pacc = this.saturate(val);
+    }
+    /**
+     * Sets a register value with hardware-accurate saturation and quantization.
+     * @param idx Register index (0-63)
+     * @param val Raw value (float)
+     */
+    setRegister(idx, val) {
+        if (idx < 0 || idx >= (32 + this.regCount))
+            return;
+        // POT registers (16, 17, 18) are 10-bit quantized 0..1
+        if (idx >= 16 && idx <= 18) {
+            val = Math.floor(Math.max(0, Math.min(0.9999999, val)) * 1024) / 1024;
+        }
+        else {
+            // Other registers (ADC, DAC, User) are S.23 saturated
+            val = this.saturate(val);
+        }
+        this.registers[idx] = val;
+    }
+    /**
+     * Evaluates a string expression (register name, symbol, memory suffix).
+     * @returns { result: string, value: number } or null
+     */
+    evaluateExpression(expr) {
+        let expression = expr.trim().toUpperCase();
+        // Handle suffixes ^ and #
+        let suffix = "";
+        if (expression.endsWith("^")) {
+            suffix = "^";
+            expression = expression.slice(0, -1);
+        }
+        else if (expression.endsWith("#")) {
+            suffix = "#";
+            expression = expression.slice(0, -1);
+        }
+        // 1. Check if it's a register name
+        const state = this.getState();
+        if (suffix === "" && state.registers[expression] !== undefined) {
+            return { label: expression, value: state.registers[expression] };
+        }
+        // 2. Check if it's ACC/PACC
+        if (suffix === "" && expression === "ACC") {
+            return { label: "ACC", value: this.acc };
+        }
+        if (suffix === "" && expression === "PACC") {
+            return { label: "PACC", value: this.pacc };
+        }
+        // 3. Check symbols (EQU)
+        const sym = this.symbols.find(s => s.name.toUpperCase() === expression);
+        if (sym && suffix === "") {
+            const addr = parseInt(sym.value);
+            if (!isNaN(addr) && addr >= 0 && addr <= 63) {
+                return { label: `REG[${addr}] (${sym.name})`, value: this.registers[addr] };
+            }
+        }
+        // 4. Check memories (MEM)
+        const mem = this.memories.find(m => m.name.toUpperCase() === expression);
+        if (mem && mem.start !== undefined) {
+            let addr = mem.start;
+            let typeLabel = "";
+            if (suffix === "^") {
+                addr = FV1Assembler.getMiddleAddr(mem.start, mem.size);
+                typeLabel = " (Middle)";
+            }
+            else if (suffix === "#") {
+                addr = FV1Assembler.getEndAddr(mem.start, mem.size, this.fv1AsmMemBug);
+                typeLabel = " (End)";
+            }
+            if (addr >= 0 && addr < this.delaySize) {
+                return { label: `MEM[${addr}] (${mem.name}${typeLabel})`, value: this.delayRam[addr] };
+            }
+        }
+        // 5. Check DELAY[idx]
+        if (suffix === "") {
+            const delayMatch = expression.match(/^DELAY\[(\d+)\]$/);
+            if (delayMatch) {
+                const idx = parseInt(delayMatch[1]);
+                if (idx >= 0 && idx < this.delaySize) {
+                    return { label: `DELAY[${idx}]`, value: this.delayRam[idx] };
+                }
+            }
+        }
+        return null;
+    }
+    getState() {
+        return {
+            pc: this.pc,
+            acc: this.acc,
+            pacc: this.pacc,
+            lr: this.lr,
+            lfo: this.lfo,
+            // Official Register Naming
+            registers: Object.fromEntries(Array.from({ length: 32 + this.regCount }, (_, i) => {
+                let name = `[${i}]`;
+                if (i === 0)
+                    name = "SIN0_RATE";
+                else if (i === 1)
+                    name = "SIN0_RANGE";
+                else if (i === 2)
+                    name = "SIN1_RATE";
+                else if (i === 3)
+                    name = "SIN1_RANGE";
+                else if (i === 4)
+                    name = "RMP0_RATE";
+                else if (i === 5)
+                    name = "RMP0_RANGE";
+                else if (i === 6)
+                    name = "RMP1_RATE";
+                else if (i === 7)
+                    name = "RMP1_RANGE";
+                else if (i === 8)
+                    name = "SIN0";
+                else if (i === 9)
+                    name = "COS0";
+                else if (i === 10)
+                    name = "SIN1";
+                else if (i === 11)
+                    name = "COS1";
+                else if (i === 12)
+                    name = "RMP0";
+                else if (i === 13)
+                    name = "RMP1";
+                else if (i === 16)
+                    name = "POT0";
+                else if (i === 17)
+                    name = "POT1";
+                else if (i === 18)
+                    name = "POT2";
+                else if (i === 20)
+                    name = "ADCL";
+                else if (i === 21)
+                    name = "ADCR";
+                else if (i === 22)
+                    name = "DACL";
+                else if (i === 23)
+                    name = "DACR";
+                else if (i === 24)
+                    name = "ADDR_PTR";
+                else if (i >= 32 && i <= 63)
+                    name = `REG${i - 32}`;
+                return [name, this.registers[i]];
+            })),
+            // Flags
+            flags: {
+                RUN: this.firstRun,
+                ZRC: (this.acc * this.pacc < 0),
+                ZRO: (this.acc === 0),
+                GEZ: (this.acc >= 0),
+                NEG: (this.acc < 0)
+            },
+            // LFO Internal positions
+            lfoState: {
+                sin0: this.sin0, cos0: this.cos0,
+                sin1: this.sin1, cos1: this.cos1,
+                rmp0: this.rmp0, rmp1: this.rmp1
+            }
+        };
+    }
+    getCycleCount() {
+        return this.cycleCount;
+    }
+    getReadOffsets() {
+        return Array.from(this.currentReadOffsets);
+    }
+    getRegisters() {
+        return this.registers;
+    }
+    updateLFOs() {
+        // Sync internal LFO modulations explicitly modified by WRAX or WRHX
+        this.sin0_rate = this.registers[0];
+        this.sin0_range = this.registers[1];
+        this.sin1_rate = this.registers[2];
+        this.sin1_range = this.registers[3];
+        this.rmp0_rate = this.registers[4];
+        this.rmp0_range = this.registers[5];
+        this.rmp1_rate = this.registers[6];
+        this.rmp1_range = this.registers[7];
+        // C logic update_rmp0/1
+        this.rmp0 -= this.rmp0_rate * (1.0 / 4096.0);
+        while (this.rmp0 >= 1.0)
+            this.rmp0 -= 1.0;
+        while (this.rmp0 < 0.0)
+            this.rmp0 += 1.0;
+        this.rmp1 -= this.rmp1_rate * (1.0 / 4096.0);
+        while (this.rmp1 >= 1.0)
+            this.rmp1 -= 1.0;
+        while (this.rmp1 < 0.0)
+            this.rmp1 += 1.0;
+        // SIN LFO update using coupled-form oscillator.
+        // The FV-1 hardware updates cos first, then uses the updated cos for sin.
+        // Clamp to [-1.0, MAX_ACC] to prevent float drift from exceeding the
+        // FV-1's 24-bit fixed-point register range.
+        const x0 = this.sin0_rate * (1.0 / 256.0);
+        this.cos0 += x0 * this.sin0;
+        this.sin0 -= x0 * this.cos0;
+        this.sin0 = Math.max(FV1Simulator.MIN_ACC, Math.min(FV1Simulator.MAX_ACC, this.sin0));
+        this.cos0 = Math.max(FV1Simulator.MIN_ACC, Math.min(FV1Simulator.MAX_ACC, this.cos0));
+        const x1 = this.sin1_rate * (1.0 / 256.0);
+        this.cos1 += x1 * this.sin1;
+        this.sin1 -= x1 * this.cos1;
+        this.sin1 = Math.max(FV1Simulator.MIN_ACC, Math.min(FV1Simulator.MAX_ACC, this.sin1));
+        this.cos1 = Math.max(FV1Simulator.MIN_ACC, Math.min(FV1Simulator.MAX_ACC, this.cos1));
+    }
+    updateStateRegisters() {
+        // ONLY update accumulators here! Rate/Range is dictated by the program loop!
+        // Writing registers[0..7] here would explicitly overwrite mid-frame WRAX modulations!
+        // LFO State Accumulators
+        this.registers[8] = this.sin0;
+        this.registers[9] = this.cos0;
+        this.registers[10] = this.sin1;
+        this.registers[11] = this.cos1;
+        this.registers[12] = this.rmp0;
+        this.registers[13] = this.rmp1;
+    }
+    getDelayRam() {
+        return this.delayRam;
+    }
+    // --- Helpers ---
+    decodeS1_14(raw) {
+        // 16 bits: 1 sign, 1 integer, 14 fractional
+        if (raw & 0x8000)
+            return (raw - 0x10000) / 16384.0;
+        return raw / 16384.0;
+    }
+    decodeS1_9(raw) {
+        // 11 bits: 1 sign, 1 integer, 9 fractional
+        if (raw & 0x400)
+            return (raw - 0x800) / 512.0;
+        return raw / 512.0;
+    }
+    decodeS_10(raw) {
+        // 11 bits: 1 sign, 0 integer, 10 fractional
+        if (raw & 0x400)
+            return (raw - 0x800) / 1024.0;
+        return raw / 1024.0;
+    }
+    decodeS4_6(raw) {
+        // 11 bits: 1 sign, 4 integer, 6 fractional
+        if (raw & 0x400)
+            return (raw - 0x800) / 64.0;
+        return raw / 64.0;
+    }
+    decodeS_15(raw) {
+        // 16 bits: 1 sign, 0 integer, 15 fractional
+        if (raw & 0x8000)
+            return (raw - 0x10000) / 32768.0;
+        return raw / 32768.0;
+    }
+    saturate(val) {
+        if (val > FV1Simulator.MAX_ACC)
+            return FV1Simulator.MAX_ACC;
+        if (val < FV1Simulator.MIN_ACC)
+            return FV1Simulator.MIN_ACC;
+        return val;
+    }
+    /**
+     * Enable trace logging with a streaming writer callback.
+     * Each row is emitted immediately via the writer — nothing is stored in memory.
+     * @param writer Callback that receives each CSV row (including header).
+     * @param maxCycles Maximum number of sample cycles to log (0 = unlimited).
+     * @param onComplete Optional callback when trace auto-completes.
+     */
+    enableTrace(writer, maxCycles = 0, onComplete) {
+        this.traceEnabled = true;
+        this.traceWriter = writer;
+        this.traceMaxCycles = maxCycles;
+        this.traceCycle = 0;
+        this.traceRowCount = 0;
+        this.traceOnComplete = onComplete || null;
+        // Emit CSV Header immediately (Reduced set for delay debugging)
+        writer(`cycle,pc,opcode,delay_op,delay_offset,delay_addr,delay_ptr`);
+        console.log(`[FV1 Trace] Logging enabled (maxCycles=${maxCycles || 'unlimited'})`);
+    }
+    /**
+     * Disable trace logging.
+     */
+    disableTrace() {
+        this.traceEnabled = false;
+        this.traceWriter = null;
+        console.log(`[FV1 Trace] Logging disabled. ${this.traceRowCount} rows written.`);
+    }
+    /**
+     * Returns whether trace logging is currently active.
+     */
+    isTraceEnabled() {
+        return this.traceEnabled;
+    }
+    /**
+     * Returns the number of trace rows emitted so far.
+     */
+    getTraceRowCount() {
+        return this.traceRowCount;
+    }
+    /**
+     * Called at end-of-frame to advance the trace cycle counter.
+     * If maxCycles is reached, trace is automatically disabled.
+     */
+    advanceTraceCycle() {
+        if (!this.traceEnabled)
+            return;
+        this.traceCycle++;
+        if (this.traceMaxCycles > 0 && this.traceCycle >= this.traceMaxCycles) {
+            const onComplete = this.traceOnComplete;
+            this.disableTrace();
+            if (onComplete)
+                onComplete();
+        }
+    }
+    logTrace(pc, opcode, inst, accBefore) {
+        if (!this.traceWriter)
+            return;
+        // FILTER: Only log delay memory operations
+        if (this.traceDelayOp === '')
+            return;
+        const opName = FV1Simulator.OPCODE_NAMES[opcode] || `?${opcode.toString(16)}`;
+        // Resolve CHO sub-type
+        let fullOpName = opName;
+        if (opcode === 0x14) {
+            const mode = (inst >>> 30) & 0x3;
+            if (mode === 0)
+                fullOpName = 'CHO_RDA';
+            else if (mode === 2) {
+                // CHO_SOF does not access delay RAM, so we filter it out
+                return;
+            }
+            else if (mode === 3)
+                fullOpName = 'CHO_RDAL';
+        }
+        else if (opcode === 0x12) {
+            // WLDS/WLDR do not access delay RAM directly in a way we track here
+            return;
+        }
+        const row = `${this.traceCycle},${pc},${fullOpName},` +
+            `${this.traceDelayOp},${this.traceDelayOp !== '' ? this.traceDelayOffset : ''},${this.traceDelayAddr >= 0 ? this.traceDelayAddr : ''},${this.delayPointer}`;
+        this.traceWriter(row);
+        this.traceRowCount++;
+    }
+}
+FV1Simulator.MAX_ACC = 1.0 - (1.0 / 8388608.0); // 24-bit S.23: 1 - 2^-23
+FV1Simulator.MIN_ACC = -FV1Simulator.MAX_ACC; // Symmetrically bound to prevent limits bias
+// --- Trace Logging System ---
+FV1Simulator.OPCODE_NAMES = {
+    0x00: 'RDA', 0x01: 'RMPA', 0x02: 'WRA', 0x03: 'WRAP',
+    0x04: 'RDAX', 0x05: 'RDFX', 0x06: 'WRAX', 0x07: 'WRHX',
+    0x08: 'WRLX', 0x09: 'MAXX', 0x0A: 'MULX', 0x0B: 'LOG',
+    0x0C: 'EXP', 0x0D: 'SOF', 0x0E: 'AND', 0x0F: 'OR',
+    0x10: 'XOR', 0x11: 'SKP', 0x12: 'WLDx', 0x13: 'JAM',
+    0x14: 'CHO'
+};
+//# sourceMappingURL=FV1Simulator.js.map