web-a2e 1.0.0

package/src/js/debug/index.js

@@ -0,0 +1,22 @@
+/*
+ * index.js - Debug subsystem module exports
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+export { BaseWindow } from "../windows/base-window.js";
+export { WindowManager } from "../windows/window-manager.js";
+export { CPUDebuggerWindow } from "./cpu-debugger-window.js";
+export { SoftSwitchWindow } from "./soft-switch-window.js";
+export { MemoryBrowserWindow } from "./memory-browser-window.js";
+export { MemoryHeatMapWindow } from "./memory-heat-map-window.js";
+export { MemoryMapWindow } from "./memory-map-window.js";
+export { StackViewerWindow } from "./stack-viewer-window.js";
+export { ZeroPageWatchWindow } from "./zero-page-watch-window.js";
+export { MockingboardWindow } from "./mockingboard-window.js";
+export { MouseCardWindow } from "./mouse-card-window.js";
+export { BasicProgramWindow } from "./basic-program-window.js";
+export { RuleBuilderWindow } from "./rule-builder-window.js";
+export { AssemblerEditorWindow } from "./assembler-editor-window.js";
+export { TracePanelWindow } from "./trace-panel.js";

package/src/js/debug/label-manager.js

@@ -0,0 +1,238 @@
+/*
+ * label-manager.js - User-defined label and imported symbol management
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+/**
+ * LabelManager - Manages user-defined labels, imported symbols, and inline comments.
+ * Provides a unified lookup layer on top of the built-in symbols.js data.
+ */
+export class LabelManager {
+  constructor() {
+    this.userLabels = new Map();     // address -> {name, comment}
+    this.importedLabels = new Map(); // address -> {name, source}
+    this.listeners = [];
+
+    this.load();
+  }
+
+  static STORAGE_KEY = "a2e-user-labels";
+
+  onChange(fn) {
+    this.listeners.push(fn);
+  }
+
+  _notify() {
+    for (const fn of this.listeners) fn();
+  }
+
+  /**
+   * Add or update a user label
+   */
+  addLabel(address, name, comment = "") {
+    this.userLabels.set(address, { name, comment });
+    this.save();
+    this._notify();
+  }
+
+  /**
+   * Remove a user label
+   */
+  removeLabel(address) {
+    if (this.userLabels.delete(address)) {
+      this.save();
+      this._notify();
+    }
+  }
+
+  /**
+   * Set inline comment for an address
+   */
+  setComment(address, comment) {
+    const existing = this.userLabels.get(address);
+    if (existing) {
+      existing.comment = comment;
+    } else {
+      this.userLabels.set(address, { name: "", comment });
+    }
+    this.save();
+    this._notify();
+  }
+
+  /**
+   * Get label info for an address. User labels take priority over imports.
+   * @returns {object|null} {name, comment, source} or null
+   */
+  getLabel(address) {
+    const user = this.userLabels.get(address);
+    if (user && user.name) {
+      return { name: user.name, comment: user.comment || "", source: "user" };
+    }
+
+    const imported = this.importedLabels.get(address);
+    if (imported) {
+      return { name: imported.name, comment: "", source: imported.source };
+    }
+
+    // Check for comment-only user entry
+    if (user && user.comment) {
+      return { name: "", comment: user.comment, source: "user" };
+    }
+
+    return null;
+  }
+
+  /**
+   * Resolve an address by label name (case-insensitive)
+   * @returns {number|null}
+   */
+  resolveByName(name) {
+    const upper = name.toUpperCase();
+
+    for (const [addr, info] of this.userLabels) {
+      if (info.name && info.name.toUpperCase() === upper) return addr;
+    }
+
+    for (const [addr, info] of this.importedLabels) {
+      if (info.name.toUpperCase() === upper) return addr;
+    }
+
+    return null;
+  }
+
+  /**
+   * Import a symbol file. Supports ca65 .dbg, Merlin, ACME, and generic formats.
+   * @param {string} text File content
+   * @param {string} source Descriptive source name (e.g. filename)
+   */
+  importSymbolFile(text, source = "import") {
+    const lines = text.split(/\r?\n/);
+    let count = 0;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith(";") || trimmed.startsWith("*")) continue;
+
+      let match;
+
+      // ca65 .dbg format: sym	name="LABEL",addrsize=absolute,scope=0,def=123,ref=...,val=0xXXXX,type=lab
+      match = trimmed.match(/^sym\s.*name="([^"]+)".*val=(0x[0-9A-Fa-f]+)/);
+      if (match) {
+        const name = match[1];
+        const addr = parseInt(match[2], 16);
+        if (addr >= 0 && addr <= 0xffff) {
+          this.importedLabels.set(addr, { name, source });
+          count++;
+        }
+        continue;
+      }
+
+      // Merlin format: LABEL EQU $XXXX
+      match = trimmed.match(/^(\w+)\s+EQU\s+\$([0-9A-Fa-f]{1,4})/i);
+      if (match) {
+        const name = match[1];
+        const addr = parseInt(match[2], 16);
+        if (addr >= 0 && addr <= 0xffff) {
+          this.importedLabels.set(addr, { name, source });
+          count++;
+        }
+        continue;
+      }
+
+      // ACME format: LABEL = $XXXX  or  !addr LABEL = $XXXX
+      match = trimmed.match(/^(?:!addr\s+)?(\w+)\s*=\s*\$([0-9A-Fa-f]{1,4})/i);
+      if (match) {
+        const name = match[1];
+        const addr = parseInt(match[2], 16);
+        if (addr >= 0 && addr <= 0xffff) {
+          this.importedLabels.set(addr, { name, source });
+          count++;
+        }
+        continue;
+      }
+
+      // Generic: $XXXX LABEL  or  XXXX LABEL
+      match = trimmed.match(/^\$?([0-9A-Fa-f]{2,4})\s+(\w+)/);
+      if (match) {
+        const addr = parseInt(match[1], 16);
+        const name = match[2];
+        if (addr >= 0 && addr <= 0xffff && !/^[0-9A-Fa-f]+$/.test(name)) {
+          this.importedLabels.set(addr, { name, source });
+          count++;
+        }
+        continue;
+      }
+    }
+
+    this._notify();
+    return count;
+  }
+
+  /**
+   * Clear imported labels from a specific source
+   */
+  clearImportedBySource(source) {
+    for (const [addr, info] of this.importedLabels) {
+      if (info.source === source) {
+        this.importedLabels.delete(addr);
+      }
+    }
+    this._notify();
+  }
+
+  /**
+   * Clear all imported labels
+   */
+  clearImported() {
+    this.importedLabels.clear();
+    this._notify();
+  }
+
+  /**
+   * Export user labels as text (generic format)
+   */
+  exportLabels() {
+    const lines = [];
+    for (const [addr, info] of this.userLabels) {
+      if (!info.name) continue;
+      const hex = addr.toString(16).toUpperCase().padStart(4, "0");
+      let line = `$${hex} ${info.name}`;
+      if (info.comment) line += `  ; ${info.comment}`;
+      lines.push(line);
+    }
+    return lines.join("\n");
+  }
+
+  // ---- Persistence ----
+
+  save() {
+    try {
+      const data = [];
+      for (const [addr, info] of this.userLabels) {
+        data.push({ address: addr, name: info.name, comment: info.comment });
+      }
+      localStorage.setItem(LabelManager.STORAGE_KEY, JSON.stringify(data));
+    } catch (e) {
+      console.warn("Failed to save labels:", e);
+    }
+  }
+
+  load() {
+    try {
+      const saved = localStorage.getItem(LabelManager.STORAGE_KEY);
+      if (saved) {
+        const data = JSON.parse(saved);
+        for (const entry of data) {
+          this.userLabels.set(entry.address, {
+            name: entry.name || "",
+            comment: entry.comment || "",
+          });
+        }
+      }
+    } catch (e) {
+      console.warn("Failed to load labels:", e);
+    }
+  }
+}

package/src/js/debug/memory-browser-window.js

@@ -0,0 +1,416 @@
+/*
+ * memory-browser-window.js - Scrollable hex/ASCII memory browser for 64KB address space
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+import { BaseWindow } from "../windows/base-window.js";
+
+// Memory region definitions for Apple II
+const MEMORY_REGIONS = [
+  { name: "Zero Page", start: 0x0000, end: 0x00ff },
+  { name: "Stack", start: 0x0100, end: 0x01ff },
+  { name: "Input Buffer", start: 0x0200, end: 0x02ff },
+  { name: "Vectors/Data", start: 0x0300, end: 0x03ff },
+  { name: "Text Page 1", start: 0x0400, end: 0x07ff },
+  { name: "Text Page 2", start: 0x0800, end: 0x0bff },
+  { name: "Free RAM", start: 0x0c00, end: 0x1fff },
+  { name: "HiRes Page 1", start: 0x2000, end: 0x3fff },
+  { name: "HiRes Page 2", start: 0x4000, end: 0x5fff },
+  { name: "Free RAM", start: 0x6000, end: 0x95ff },
+  { name: "DOS 3.3", start: 0x9600, end: 0xbfff },
+  { name: "I/O Space", start: 0xc000, end: 0xc0ff },
+  { name: "Slot ROMs", start: 0xc100, end: 0xcfff },
+  { name: "ROM/LC RAM", start: 0xd000, end: 0xffff },
+];
+
+// Quick jump buttons
+const QUICK_JUMPS = [
+  { label: "ZP", addr: 0x0000, title: "Zero Page ($0000)" },
+  { label: "Stack", addr: 0x0100, title: "Stack ($0100)" },
+  { label: "Text1", addr: 0x0400, title: "Text Page 1 ($0400)" },
+  { label: "Text2", addr: 0x0800, title: "Text Page 2 ($0800)" },
+  { label: "HiRes1", addr: 0x2000, title: "HiRes Page 1 ($2000)" },
+  { label: "HiRes2", addr: 0x4000, title: "HiRes Page 2 ($4000)" },
+  { label: "I/O", addr: 0xc000, title: "I/O Space ($C000)" },
+  { label: "ROM", addr: 0xd000, title: "ROM / Language Card ($D000)" },
+  { label: "Vectors", addr: 0xfff0, title: "Vectors ($FFF0)" },
+  { label: "DOS", addr: 0x9600, title: "DOS 3.3 ($9600)" },
+];
+
+export class MemoryBrowserWindow extends BaseWindow {
+  constructor(wasmModule) {
+    super({
+      id: "memory-browser",
+      title: "Memory Browser",
+      defaultWidth: 600,
+      defaultHeight: 520,
+      minWidth: 600,
+      minHeight: 300,
+      maxWidth: 600,
+    });
+    this.wasmModule = wasmModule;
+    this.baseAddress = 0x0000;
+    this.bytesPerRow = 16;
+    this.visibleRows = 28;
+    this.previousMemory = new Uint8Array(65536);
+    this.changedBytes = new Set();
+    this.changeTimestamps = new Map();
+  }
+
+  renderContent() {
+    return `
+      <div class="mem-browser-toolbar">
+        <div class="mem-browser-jumps">
+          ${QUICK_JUMPS.map(
+            (j) =>
+              `<button class="mem-jump-btn" data-addr="${j.addr}" title="${j.title}">${j.label}</button>`,
+          ).join("")}
+        </div>
+        <div class="mem-browser-nav">
+          <input type="text" class="mem-addr-input" placeholder="Address" maxlength="4" />
+          <button class="mem-go-btn" title="Go to address">Go</button>
+          <input type="text" class="mem-search-input" placeholder="Search hex" maxlength="16" />
+          <button class="mem-search-btn" title="Search for bytes">Find</button>
+          <button class="mem-refresh-btn" title="Refresh memory view">Refresh</button>
+        </div>
+      </div>
+      <div class="mem-browser-region">Region: <span class="mem-region-name">Zero Page</span></div>
+      <div class="mem-browser-header">
+        <span class="mem-addr-col">Addr</span>
+        <span class="mem-hdr-separator">:</span>
+        <span class="mem-hdr-bytes">${Array.from({ length: 16 }, (_, i) => i.toString(16).toUpperCase().padStart(2, "0")).join(" ")} </span>
+        <span class="mem-ascii-sep">&nbsp;</span>
+        <span class="mem-ascii-hdr">ASCII</span>
+        <span class="mem-ascii-sep">&nbsp;</span>
+      </div>
+      <div class="mem-browser-scroll-container">
+        <div class="mem-browser-content"></div>
+        <div class="mem-browser-scrollbar">
+          <div class="mem-scrollbar-track">
+            <div class="mem-scrollbar-thumb"></div>
+          </div>
+        </div>
+      </div>
+    `;
+  }
+
+  onContentRendered() {
+    this.contentDiv = this.contentElement.querySelector(".mem-browser-content");
+    this.scrollContainer = this.contentElement.querySelector(
+      ".mem-browser-scroll-container",
+    );
+    this.scrollbarThumb = this.contentElement.querySelector(
+      ".mem-scrollbar-thumb",
+    );
+    this.regionNameSpan = this.contentElement.querySelector(".mem-region-name");
+    this.addrInput = this.contentElement.querySelector(".mem-addr-input");
+    this.searchInput = this.contentElement.querySelector(".mem-search-input");
+
+    this.setupScrolling();
+    this.setupContentEventListeners();
+  }
+
+  setupScrolling() {
+    // Mouse wheel scrolling - explicitly non-passive since we need preventDefault()
+    this.scrollContainer.addEventListener(
+      "wheel",
+      (e) => {
+        e.preventDefault();
+        const delta = Math.sign(e.deltaY) * this.bytesPerRow * 4;
+        this.scrollToAddress(this.baseAddress + delta);
+      },
+      { passive: false },
+    );
+
+    // Scrollbar dragging
+    let isDragging = false;
+    let dragStartY = 0;
+    let dragStartAddr = 0;
+
+    this.scrollbarThumb.addEventListener("mousedown", (e) => {
+      isDragging = true;
+      dragStartY = e.clientY;
+      dragStartAddr = this.baseAddress;
+      e.preventDefault();
+    });
+
+    document.addEventListener("mousemove", (e) => {
+      if (!isDragging) return;
+      const trackHeight =
+        this.scrollbarThumb.parentElement.offsetHeight -
+        this.scrollbarThumb.offsetHeight;
+      const deltaY = e.clientY - dragStartY;
+      const maxAddress = 0x10000 - this.bytesPerRow * this.visibleRows;
+      const newAddr = Math.round(
+        dragStartAddr + (deltaY / trackHeight) * maxAddress,
+      );
+      this.scrollToAddress(newAddr);
+    });
+
+    document.addEventListener("mouseup", () => {
+      isDragging = false;
+    });
+
+    // Track click
+    this.scrollbarThumb.parentElement.addEventListener("click", (e) => {
+      if (e.target === this.scrollbarThumb) return;
+      const rect = this.scrollbarThumb.parentElement.getBoundingClientRect();
+      const clickY = e.clientY - rect.top;
+      const trackHeight = rect.height;
+      const maxAddress = 0x10000 - this.bytesPerRow * this.visibleRows;
+      const newAddr = Math.round((clickY / trackHeight) * maxAddress);
+      this.scrollToAddress(newAddr);
+    });
+  }
+
+  setupContentEventListeners() {
+    // Quick jump buttons
+    this.contentElement.querySelectorAll(".mem-jump-btn").forEach((btn) => {
+      btn.addEventListener("click", () => {
+        const addr = parseInt(btn.dataset.addr, 10);
+        this.scrollToAddress(addr);
+      });
+    });
+
+    // Go button
+    this.contentElement
+      .querySelector(".mem-go-btn")
+      .addEventListener("click", () => {
+        this.goToAddress();
+      });
+
+    // Address input enter key
+    this.addrInput.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") {
+        this.goToAddress();
+      }
+    });
+
+    // Search button
+    this.contentElement
+      .querySelector(".mem-search-btn")
+      .addEventListener("click", () => {
+        this.searchBytes();
+      });
+
+    // Search input enter key
+    this.searchInput.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") {
+        this.searchBytes();
+      }
+    });
+
+    // Refresh button
+    this.contentElement
+      .querySelector(".mem-refresh-btn")
+      .addEventListener("click", () => {
+        this.forceRefresh = true;
+      });
+
+    // Byte click to edit
+    this.contentDiv.addEventListener("click", (e) => {
+      const byteSpan = e.target.closest(".mem-byte");
+      if (byteSpan && byteSpan.dataset.addr) {
+        this.startEditByte(parseInt(byteSpan.dataset.addr, 10));
+      }
+    });
+  }
+
+  goToAddress() {
+    const input = this.addrInput.value.trim();
+    let addr = parseInt(input, 16);
+    if (isNaN(addr)) {
+      addr = parseInt(input, 10);
+    }
+    if (!isNaN(addr) && addr >= 0 && addr <= 0xffff) {
+      this.scrollToAddress(addr);
+    }
+  }
+
+  searchBytes() {
+    const input = this.searchInput.value.trim().replace(/\s/g, "");
+    if (input.length === 0 || input.length % 2 !== 0) return;
+
+    const bytes = [];
+    for (let i = 0; i < input.length; i += 2) {
+      const byte = parseInt(input.substr(i, 2), 16);
+      if (isNaN(byte)) return;
+      bytes.push(byte);
+    }
+
+    // Search from current position + 1
+    const startAddr = this.baseAddress + 1;
+    for (let i = 0; i < 65536; i++) {
+      const addr = (startAddr + i) & 0xffff;
+      let found = true;
+      for (let j = 0; j < bytes.length; j++) {
+        if (this.wasmModule._peekMemory((addr + j) & 0xffff) !== bytes[j]) {
+          found = false;
+          break;
+        }
+      }
+      if (found) {
+        this.scrollToAddress(addr);
+        return;
+      }
+    }
+  }
+
+  scrollToAddress(addr) {
+    // Align to row boundary and clamp
+    addr = Math.floor(addr / this.bytesPerRow) * this.bytesPerRow;
+    addr = Math.max(
+      0,
+      Math.min(addr, 0x10000 - this.bytesPerRow * this.visibleRows),
+    );
+    if (addr !== this.baseAddress) {
+      this.baseAddress = addr;
+      this.forceRefresh = true;
+      if (this.onStateChange) this.onStateChange();
+    }
+    this.updateScrollbar();
+    this.updateRegionName();
+  }
+
+  updateScrollbar() {
+    const maxAddress = 0x10000 - this.bytesPerRow * this.visibleRows;
+    const thumbHeight = Math.max(
+      20,
+      (this.visibleRows * this.bytesPerRow * 100) / 65536,
+    );
+    const thumbPosition = (this.baseAddress / maxAddress) * (100 - thumbHeight);
+    this.scrollbarThumb.style.height = `${thumbHeight}%`;
+    this.scrollbarThumb.style.top = `${thumbPosition}%`;
+  }
+
+  updateRegionName() {
+    const addr = this.baseAddress;
+    for (const region of MEMORY_REGIONS) {
+      if (addr >= region.start && addr <= region.end) {
+        this.regionNameSpan.textContent = region.name;
+        return;
+      }
+    }
+    this.regionNameSpan.textContent = "Unknown";
+  }
+
+  startEditByte(addr) {
+    const currentValue = this.wasmModule._peekMemory(addr);
+    const newValueStr = prompt(
+      `Edit $${this.formatHex(addr, 4)}\nCurrent value: $${this.formatHex(currentValue, 2)}`,
+      this.formatHex(currentValue, 2),
+    );
+    if (newValueStr !== null) {
+      const newValue = parseInt(newValueStr, 16);
+      if (!isNaN(newValue) && newValue >= 0 && newValue <= 255) {
+        this.wasmModule._writeMemory(addr, newValue);
+      }
+    }
+  }
+
+  getRegionForAddress(addr) {
+    for (const region of MEMORY_REGIONS) {
+      if (addr >= region.start && addr <= region.end) {
+        return region.name;
+      }
+    }
+    return "Unknown";
+  }
+
+  update(wasmModule) {
+    if (!this.isVisible || !this.contentDiv) return;
+    if (!wasmModule._isPaused() && !this.forceRefresh) return;
+    this.forceRefresh = false;
+
+    const now = Date.now();
+    const fadeTime = 1000;
+
+    let html = "";
+    for (let row = 0; row < this.visibleRows; row++) {
+      const rowAddr = this.baseAddress + row * this.bytesPerRow;
+      if (rowAddr >= 0x10000) break;
+
+      html += `<div class="mem-row"><span class="mem-addr">${this.formatAddr(rowAddr)}</span><span class="mem-separator">:</span>`;
+
+      // Hex bytes
+      for (let col = 0; col < this.bytesPerRow; col++) {
+        if (col === 8) html += " ";
+
+        const addr = rowAddr + col;
+        if (addr >= 0x10000) break;
+
+        const value = wasmModule._peekMemory(addr);
+        const prevValue = this.previousMemory[addr];
+
+        if (value !== prevValue) {
+          this.changedBytes.add(addr);
+          this.changeTimestamps.set(addr, now);
+          this.previousMemory[addr] = value;
+        }
+
+        let byteClass = "mem-byte";
+        if (value === 0x00) {
+          byteClass += " mem-zero";
+        } else if (value >= 0x20 && value < 0x7f) {
+          byteClass += " mem-printable";
+        } else if (value >= 0x80) {
+          byteClass += " mem-highbit";
+        }
+
+        if (this.changeTimestamps.has(addr)) {
+          const elapsed = now - this.changeTimestamps.get(addr);
+          if (elapsed < fadeTime) {
+            byteClass += " changed";
+          } else {
+            this.changeTimestamps.delete(addr);
+          }
+        }
+
+        html += `<span class="${byteClass}" data-addr="${addr}">${this.formatHex(value, 2)}</span>`;
+      }
+
+      // ASCII
+      html += '<span class="mem-ascii">';
+      for (let col = 0; col < this.bytesPerRow; col++) {
+        const addr = rowAddr + col;
+        if (addr >= 0x10000) break;
+        const value = wasmModule._peekMemory(addr);
+        const ch = value & 0x7f;
+        html += ch >= 0x20 && ch < 0x7f ? String.fromCharCode(ch) : ".";
+      }
+      html += "</span></div>";
+    }
+
+    this.contentDiv.innerHTML = html;
+  }
+
+  getState() {
+    const base = super.getState();
+    base.baseAddress = this.baseAddress;
+    return base;
+  }
+
+  restoreState(state) {
+    if (state.baseAddress !== undefined) {
+      this.baseAddress = state.baseAddress;
+    }
+    super.restoreState(state);
+  }
+
+  show() {
+    super.show();
+    // Apply restored base address to UI after content is rendered
+    if (this.contentDiv) {
+      this.updateScrollbar();
+      this.updateRegionName();
+      this.forceRefresh = true;
+    }
+  }
+
+  // Allow external code to jump to a specific address
+  jumpToAddress(addr) {
+    this.scrollToAddress(addr);
+  }
+}