web-a2e 1.0.0

package/src/js/audio/audio-driver.js

@@ -0,0 +1,417 @@
+/*
+ * audio-driver.js - Web Audio API driver for emulator audio and timing
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+// Audio constants
+const SAMPLE_RATE = 48000;
+const AUDIO_BUFFER_SIZE = 128; // AudioWorklet processes 128 samples at a time
+const CYCLES_PER_SECOND = 1023000;
+const DEFAULT_VOLUME = 0.5;
+
+export class AudioDriver {
+  constructor(wasmModule) {
+    this.wasmModule = wasmModule;
+    this.audioContext = null;
+    this.workletNode = null;
+    this.gainNode = null;
+
+    this.sampleRate = SAMPLE_RATE;
+    this.bufferSize = AUDIO_BUFFER_SIZE;
+    this.running = false;
+    this.muted = this.loadMuted();
+    this.volume = this.loadVolume(); // Load saved volume or default to 0.5
+    this.speed = 1;
+
+    // Fallback to ScriptProcessorNode if AudioWorklet not available
+    this.useWorklet = typeof AudioWorkletNode !== "undefined";
+    this.scriptProcessor = null;
+
+    // Frame synchronization callback
+    this.onFrameReady = null;
+
+    // Pre-allocated WASM buffer for audio sample generation to avoid
+    // malloc/free churn (~375 calls/sec) that causes GC stutter in Safari/Brave
+    this.wasmBufferPtr = 0;
+    this.wasmBufferSamples = 0;
+
+    // Sync C++ audio state with saved JS settings
+    if (this.wasmModule._setAudioVolume) {
+      this.wasmModule._setAudioVolume(this.volume);
+    }
+    if (this.wasmModule._setAudioMuted) {
+      this.wasmModule._setAudioMuted(this.muted);
+    }
+  }
+
+  async start() {
+    if (this.running) return;
+
+    try {
+      // Create audio context
+      this.audioContext = new (window.AudioContext ||
+        window.webkitAudioContext)({
+        sampleRate: this.sampleRate,
+      });
+
+      // Check if audio context is suspended (browser autoplay policy)
+      if (this.audioContext.state === "suspended") {
+        console.log("Audio context suspended, using fallback timing until user interaction");
+        this.startFallbackTiming();
+
+        // Set up listener to resume audio on user interaction
+        this.setupAutoResumeAudio();
+        return;
+      }
+
+      await this.initAudioNodes();
+    } catch (error) {
+      console.error("Failed to start audio driver:", error);
+      // Fall back to non-audio timing
+      this.startFallbackTiming();
+    }
+  }
+
+  async initAudioNodes() {
+    // Create gain node for volume control
+    this.gainNode = this.audioContext.createGain();
+    this.gainNode.connect(this.audioContext.destination);
+    this.gainNode.gain.value = this.muted ? 0 : this.volume;
+
+    if (this.useWorklet) {
+      await this.startWithWorklet();
+    } else {
+      this.startWithScriptProcessor();
+    }
+
+    this.running = true;
+    console.log("Audio driver started");
+  }
+
+  setupAutoResumeAudio() {
+    const resumeAudio = async () => {
+      if (this.audioContext && this.audioContext.state === "suspended") {
+        try {
+          await this.audioContext.resume();
+          console.log("Audio context resumed");
+
+          // Stop fallback timing
+          if (this.fallbackInterval) {
+            clearInterval(this.fallbackInterval);
+            this.fallbackInterval = null;
+          }
+
+          // Initialize proper audio nodes
+          await this.initAudioNodes();
+        } catch (e) {
+          console.error("Failed to resume audio context:", e);
+        }
+      }
+
+      // Remove listeners after first interaction
+      document.removeEventListener("click", resumeAudio);
+      document.removeEventListener("keydown", resumeAudio);
+    };
+
+    document.addEventListener("click", resumeAudio, { once: true });
+    document.addEventListener("keydown", resumeAudio, { once: true });
+  }
+
+  async startWithWorklet() {
+    // Register the audio worklet
+    // In dev mode, load from src; in production, load from root
+    const workletPath = import.meta.env.DEV
+      ? "/src/js/audio/audio-worklet.js"
+      : "/audio-worklet.js";
+    await this.audioContext.audioWorklet.addModule(workletPath);
+
+    // Create worklet node (stereo output)
+    this.workletNode = new AudioWorkletNode(
+      this.audioContext,
+      "apple-audio-processor",
+      {
+        numberOfInputs: 0,
+        numberOfOutputs: 1,
+        outputChannelCount: [2],
+      },
+    );
+
+    // Handle messages from worklet
+    this.workletNode.port.onmessage = (event) => {
+      // Check if worklet is still valid (may be null after stop)
+      if (!this.workletNode || !this.running) {
+        return;
+      }
+      if (event.data.type === "requestSamples") {
+        const samples = this.generateSamples(event.data.count);
+        if (this.workletNode && this.workletNode.port) {
+          this.workletNode.port.postMessage({
+            type: "samples",
+            data: samples,
+          }, [samples.buffer]);
+        }
+      }
+    };
+
+    this.workletNode.connect(this.gainNode);
+
+    // Start the worklet
+    this.workletNode.port.postMessage({ type: "start" });
+  }
+
+  startWithScriptProcessor() {
+    // Fallback for browsers without AudioWorklet support (stereo)
+    this.scriptProcessor = this.audioContext.createScriptProcessor(4096, 0, 2);
+
+    this.scriptProcessor.onaudioprocess = (event) => {
+      const leftChannel = event.outputBuffer.getChannelData(0);
+      const rightChannel = event.outputBuffer.getChannelData(1);
+      const samples = this.generateSamples(leftChannel.length);
+      // Deinterleave stereo samples
+      for (let i = 0; i < leftChannel.length; i++) {
+        leftChannel[i] = samples[i * 2];
+        rightChannel[i] = samples[i * 2 + 1];
+      }
+    };
+
+    this.scriptProcessor.connect(this.gainNode);
+  }
+
+  /**
+   * Start fallback timing when Web Audio API is unavailable or suspended.
+   *
+   * The Apple IIe runs at 1.023 MHz. Normally, timing is driven by the Web Audio API's
+   * sample rate (48kHz), which provides precise timing through the audio callback.
+   * When audio is unavailable (browser autoplay policy, no audio hardware, etc.),
+   * this fallback uses setInterval at 60Hz to maintain approximate timing.
+   *
+   * At 60Hz, each tick should execute ~17,050 cycles (1,023,000 / 60).
+   * Speed multiplier allows for fast-forward (speed > 1) or unlimited speed (speed = 0).
+   *
+   * Note: setInterval timing is less precise than Web Audio, so emulation timing
+   * may be slightly off. This is acceptable for basic functionality until audio resumes.
+   */
+  startFallbackTiming() {
+    const cyclesPerTick = CYCLES_PER_SECOND / 60;
+
+    this.fallbackInterval = setInterval(() => {
+      if (this.speed === 0) {
+        // Unlimited speed - run as fast as possible
+        this.wasmModule._runCycles(cyclesPerTick * 10);
+      } else {
+        this.wasmModule._runCycles(cyclesPerTick * this.speed);
+      }
+
+      // Check for frame updates
+      const framesReady = this.wasmModule._consumeFrameSamples();
+      if (framesReady > 0 && this.onFrameReady) {
+        this.onFrameReady(framesReady);
+      }
+    }, 1000 / 60);
+
+    this.running = true;
+    console.log("Using fallback timing (no audio)");
+  }
+
+  /**
+   * Generate audio samples by running the emulator and collecting speaker output.
+   *
+   * This is the core timing mechanism: the Web Audio API requests samples at 48kHz,
+   * and we run the emulator for exactly enough cycles to produce those samples.
+   * The WASM module tracks the ratio of CPU cycles to audio samples (1,023,000 Hz / 48,000 Hz ≈ 21.3 cycles per sample).
+   *
+   * The emulator's speaker produces 1-bit audio by toggling a soft switch ($C030).
+   * The WASM module converts these toggles into floating-point samples.
+   *
+   * Frame synchronization: The emulator also counts audio samples to determine when
+   * a video frame is complete (~17,050 cycles = ~800 samples per 60Hz frame).
+   * When a frame's worth of samples is generated, we trigger onFrameReady for rendering.
+   *
+   * @param {number} count - Number of audio samples to generate
+   * @returns {Float32Array} Generated audio samples in range [-1, 1]
+   */
+  ensureWasmBuffer(count) {
+    if (this.wasmBufferSamples < count) {
+      if (this.wasmBufferPtr) {
+        this.wasmModule._free(this.wasmBufferPtr);
+      }
+      this.wasmBufferPtr = this.wasmModule._malloc(count * 2 * 4);
+      this.wasmBufferSamples = count;
+    }
+  }
+
+  generateSamples(count) {
+    this.ensureWasmBuffer(count);
+
+    this.wasmModule._generateStereoAudioSamples(this.wasmBufferPtr, count);
+
+    // Copy interleaved stereo samples from WASM memory into a new Float32Array.
+    // A new array is required because the worklet path transfers buffer ownership.
+    const samples = new Float32Array(
+      this.wasmModule.HEAPF32.buffer,
+      this.wasmBufferPtr,
+      count * 2,
+    ).slice();
+
+    // Check if we've accumulated enough samples for one or more frames
+    const framesReady = this.wasmModule._consumeFrameSamples();
+    if (framesReady > 0 && this.onFrameReady) {
+      this.onFrameReady(framesReady);
+    }
+
+    return samples;
+  }
+
+  stop() {
+    if (!this.running) return;
+
+    // Set running to false first to stop any pending callbacks
+    this.running = false;
+
+    if (this.workletNode) {
+      try {
+        this.workletNode.port.postMessage({ type: "stop" });
+        this.workletNode.disconnect();
+      } catch (e) {
+        // Ignore errors during cleanup
+      }
+      this.workletNode = null;
+    }
+
+    if (this.scriptProcessor) {
+      try {
+        this.scriptProcessor.disconnect();
+      } catch (e) {
+        // Ignore errors during cleanup
+      }
+      this.scriptProcessor = null;
+    }
+
+    if (this.fallbackInterval) {
+      clearInterval(this.fallbackInterval);
+      this.fallbackInterval = null;
+    }
+
+    if (this.wasmBufferPtr) {
+      this.wasmModule._free(this.wasmBufferPtr);
+      this.wasmBufferPtr = 0;
+      this.wasmBufferSamples = 0;
+    }
+
+    if (this.audioContext) {
+      try {
+        this.audioContext.close();
+      } catch (e) {
+        // Ignore errors during cleanup
+      }
+      this.audioContext = null;
+    }
+
+    console.log("Audio driver stopped");
+  }
+
+  /**
+   * Set emulation speed multiplier.
+   * Reserved for future speed control feature (e.g., fast-forward, slow-motion).
+   * @param {number} speed - Speed multiplier (1 = normal, 0 = unlimited)
+   */
+  setSpeed(speed) {
+    this.speed = speed;
+  }
+
+  toggleMute() {
+    this.muted = !this.muted;
+    if (this.gainNode) {
+      this.gainNode.gain.value = this.muted ? 0 : this.volume;
+    }
+    if (this.wasmModule._setAudioMuted) {
+      this.wasmModule._setAudioMuted(this.muted);
+    }
+    this.saveMuted();
+  }
+
+  isMuted() {
+    return this.muted;
+  }
+
+  mute() {
+    this.muted = true;
+    if (this.gainNode) {
+      this.gainNode.gain.value = 0;
+    }
+    if (this.wasmModule._setAudioMuted) {
+      this.wasmModule._setAudioMuted(true);
+    }
+    this.saveMuted();
+  }
+
+  unmute() {
+    this.muted = false;
+    if (this.gainNode) {
+      this.gainNode.gain.value = this.volume;
+    }
+    if (this.wasmModule._setAudioMuted) {
+      this.wasmModule._setAudioMuted(false);
+    }
+    this.saveMuted();
+  }
+
+  loadMuted() {
+    try {
+      return localStorage.getItem('a2e-muted') === 'true';
+    } catch (e) {
+      // Ignore localStorage errors
+    }
+    return false;
+  }
+
+  saveMuted() {
+    try {
+      localStorage.setItem('a2e-muted', this.muted.toString());
+    } catch (e) {
+      // Ignore localStorage errors
+    }
+  }
+
+  getVolume() {
+    return this.volume;
+  }
+
+  setVolume(volume) {
+    this.volume = Math.max(0, Math.min(1, volume));
+    if (this.gainNode) {
+      this.gainNode.gain.value = this.muted ? 0 : this.volume;
+    }
+    // Sync C++ audio volume for speaker and Mockingboard pre-mix scaling
+    if (this.wasmModule._setAudioVolume) {
+      this.wasmModule._setAudioVolume(this.volume);
+    }
+    this.saveVolume();
+  }
+
+  loadVolume() {
+    try {
+      const saved = localStorage.getItem('a2e-volume');
+      if (saved !== null) {
+        const vol = parseFloat(saved);
+        if (!isNaN(vol) && vol >= 0 && vol <= 1) {
+          return vol;
+        }
+      }
+    } catch (e) {
+      // Ignore localStorage errors
+    }
+    return DEFAULT_VOLUME;
+  }
+
+  saveVolume() {
+    try {
+      localStorage.setItem('a2e-volume', this.volume.toString());
+    } catch (e) {
+      // Ignore localStorage errors
+    }
+  }
+
+}

package/src/js/audio/audio-worklet.js

@@ -0,0 +1,85 @@
+/*
+ * audio-worklet.js - AudioWorklet processor for sample generation and emulator timing
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+class AppleAudioProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+
+    this.running = false;
+    this.sampleBuffer = new Float32Array(0); // Interleaved stereo [L0, R0, L1, R1, ...]
+    this.bufferReadPos = 0;
+    this.pendingRequest = false;
+
+    // Handle messages from main thread
+    this.port.onmessage = (event) => {
+      if (event.data.type === "start") {
+        this.running = true;
+        this.pendingRequest = false;
+      } else if (event.data.type === "stop") {
+        this.running = false;
+        this.pendingRequest = false;
+      } else if (event.data.type === "samples") {
+        // Append new interleaved stereo samples to existing buffer
+        const newSamples = event.data.data;
+        const remaining = this.sampleBuffer.length - this.bufferReadPos;
+
+        if (remaining > 0) {
+          // Append to remaining samples
+          const combined = new Float32Array(remaining + newSamples.length);
+          combined.set(this.sampleBuffer.subarray(this.bufferReadPos), 0);
+          combined.set(newSamples, remaining);
+          this.sampleBuffer = combined;
+        } else {
+          this.sampleBuffer = newSamples;
+        }
+        this.bufferReadPos = 0;
+        this.pendingRequest = false;
+      }
+    };
+  }
+
+  process(inputs, outputs, parameters) {
+    const output = outputs[0];
+    const leftChannel = output[0];
+    const rightChannel = output[1];
+
+    if (!this.running || !leftChannel) {
+      // Fill with silence
+      if (leftChannel) leftChannel.fill(0);
+      if (rightChannel) rightChannel.fill(0);
+      return true;
+    }
+
+    // Buffer contains interleaved stereo samples, so remaining frames = remaining / 2
+    const remainingFrames = (this.sampleBuffer.length - this.bufferReadPos) / 2;
+
+    // Request more samples if buffer is getting low and no request pending
+    // Keep at least 2 frames worth of buffer to avoid underruns
+    if (remainingFrames < 1600 && !this.pendingRequest) {
+      this.pendingRequest = true;
+      this.port.postMessage({
+        type: "requestSamples",
+        count: 1600, // Number of sample frames (stereo pairs)
+      });
+    }
+
+    // Copy interleaved samples to separate L/R channels
+    for (let i = 0; i < leftChannel.length; i++) {
+      if (this.bufferReadPos + 1 < this.sampleBuffer.length) {
+        leftChannel[i] = this.sampleBuffer[this.bufferReadPos++];
+        rightChannel[i] = this.sampleBuffer[this.bufferReadPos++];
+      } else {
+        leftChannel[i] = 0;
+        rightChannel[i] = 0;
+      }
+    }
+
+    return true;
+  }
+}
+
+registerProcessor("apple-audio-processor", AppleAudioProcessor);

package/src/js/audio/index.js

@@ -0,0 +1,8 @@
+/*
+ * index.js - Audio subsystem initialization and exports
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+export { AudioDriver } from "./audio-driver.js";

package/src/js/config/default-layout.js

@@ -0,0 +1,34 @@
+/*
+ * default-layout.js - Default window layout for first-time users
+ *
+ * Defines which windows are visible and their position/size when the app
+ * starts with no saved state. Windows not listed stay hidden at their
+ * constructor defaults.
+ *
+ * Special values:
+ *   "viewport-fill" — fills available viewport with margin (screen-window)
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+export const DEFAULT_LAYOUT = [
+  {
+    id: "screen-window",
+    x: 20,
+    y: 70,
+    width: 587,
+    height: 475,
+    visible: true,
+    viewportLocked: false,
+  },
+  {
+    id: "disk-drives",
+    x: 624,
+    y: 156,
+    width: 600,
+    height: 310,
+    visible: true,
+    viewportLocked: false,
+  },
+];

package/src/js/config/version.js

@@ -0,0 +1,8 @@
+/*
+ * version.js - Application version configuration
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+export const VERSION = "1.0.9";