web-a2e 1.0.0

package/public/audio-worklet.js

@@ -0,0 +1,82 @@
+// Audio Worklet Processor for Apple //e Emulator
+// This runs in a separate thread and drives emulator timing
+// Stereo output: PSG1 on left channel, PSG2 on right channel
+
+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 = new Float32Array(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/public/disks/library.json

@@ -0,0 +1,26 @@
+[
+  {
+    "id": "prodos-243",
+    "name": "ProDOS 2.4.3",
+    "file": "ProDOS 2.4.3.po",
+    "type": "floppy",
+    "size": "140 KB",
+    "description": "ProDOS 2.4.3 system disk with BASIC.SYSTEM"
+  },
+  {
+    "id": "dos33-master",
+    "name": "DOS 3.3 System Master",
+    "file": "Apple DOS 3.3 January 1983.dsk",
+    "type": "floppy",
+    "size": "140 KB",
+    "description": "Apple DOS 3.3 system master with Applesoft BASIC"
+  },
+  {
+    "id": "prodos-243-hd",
+    "name": "ProDOS 2.4.3 HD + Games",
+    "file": "h32mb.2mg",
+    "type": "hard-drive",
+    "size": "32 MB",
+    "description": "ProDOS 2.4.3 hard drive volume + games"
+  }
+]

package/public/docs/llms/llm-assembler.txt

@@ -0,0 +1,90 @@
+# Assembler
+
+> 65C02 assembly editor with Merlin syntax support.
+
+## Tool Operations
+
+**Show the window:**
+```
+showWindow("assembler-editor")
+```
+
+**Hide the window:**
+```
+hideWindow("assembler-editor")
+```
+
+**Focus the window:**
+```
+focusWindow("assembler-editor")
+```
+
+**Assemble source code:**
+```
+emma_command({ command: "asmAssemble", params: {} })
+```
+Assembles the current assembly source code in the editor.
+
+**Write assembled code to memory:**
+```
+emma_command({ command: "asmWrite", params: {} })
+```
+Writes the assembled machine code into emulator memory.
+
+**Execute assembled code:**
+```
+emma_command({ command: "directExecuteAssemblyAt", params: { addr: "$0800" } })
+emma_command({ command: "directExecuteAssemblyAt", params: { addr: "$0800", returnTo: "monitor" } })
+emma_command({ command: "directExecuteAssemblyAt", params: { addr: "$0800", returnTo: "basic" } })
+emma_command({ command: "directExecuteAssemblyAt", params: { addr: "$0800", returnTo: "$E003" } })
+```
+Sets PC to the specified address and executes. Address supports hex (`"$0800"`) or decimal (`2048`). If `addr` is omitted, uses the origin from the last successful assembly. Set `paused: true` to pause after setting PC (useful for debugging). Default is `paused: false` (executes immediately).
+
+`returnTo` pushes a return address onto the stack so programs ending with RTS return cleanly. Defaults to `"auto"`. Accepts:
+- `"auto"` (default) - captures current PC as return address (returns to whatever was running)
+- `"monitor"` - return to Apple II monitor ($FF69)
+- `"basic"` - return to Applesoft BASIC prompt ($E003)
+- `"$AABB"` - hex address
+- `12345` - decimal address
+
+**Load example program:**
+```
+emma_command({ command: "asmLoadExample", params: {} })
+```
+Loads a "Hello World" example program into the editor.
+
+**Clear editor:**
+```
+emma_command({ command: "asmNew", params: {} })
+```
+Clears the editor and starts a new assembly file.
+
+**Get assembly source:**
+```
+emma_command({ command: "asmGet", params: {} })
+```
+Retrieves the current assembly source code from the editor.
+
+**Get assembly status:**
+```
+emma_command({ command: "asmGetStatus", params: {} })
+```
+Returns the assembly status (none/ok/error), status text, origin address, and assembled size. Status is "none" when no program has been assembled.
+
+**Set assembly source:**
+```
+emma_command({ command: "asmSet", params: { source: "ORG $0800\nLDA #$00\nRTS" } })
+```
+Replaces the entire assembly source code in the editor.
+
+**Get assembly source for saving:**
+```
+emma_command({ command: "saveAsmInEditorToLocal", params: {} })
+```
+Retrieves the assembly source from the editor. Use with save_asm_file MCP tool to save to filesystem.
+
+**Save assembly source to filesystem (MCP tool):**
+```
+save_asm_file({ path: "~/Documents/program.s", content: "<source code>", overwrite: false })
+```
+Saves assembly source code to a file on the local filesystem. Supports ~ for home directory. Recommended extensions: .s, .asm.

package/public/docs/llms/llm-basic-program.txt

@@ -0,0 +1,256 @@
+# BASIC Program
+
+> View and load Applesoft and Integer BASIC programs from memory.
+
+## Tool Operations
+
+### Direct Memory Access
+
+**Read BASIC program directly from memory:**
+```
+emma_command({ command: "directReadBasic", params: {} })
+```
+Reads the BASIC program directly from emulator memory via WASM bindings. Does not require the BASIC window to be open or focused. Returns the detokenized program text.
+
+**Write BASIC program directly to memory:**
+```
+emma_command({ command: "directWriteBasic", params: { program: "10 PRINT \"HELLO\"\n20 GOTO 10" } })
+```
+Writes a BASIC program directly to emulator memory via WASM bindings. Tokenizes the program text and updates all zero-page pointers. Does not require the BASIC window to be open or focused. The emulator must be powered on.
+
+**Run BASIC program directly:**
+```
+emma_command({ command: "directRunBasic", params: {} })
+```
+Executes the BASIC program currently in memory by simulating the RUN command. Unpauses the emulator and clears any breakpoint flags. Does not require the BASIC window to be open or focused. The emulator must be powered on.
+
+**Clear BASIC program buffer (NEW):**
+```
+emma_command({ command: "directNewBasic", params: {} })
+```
+Clears the BASIC program buffer by resetting all zero-page pointers and writing the end-of-program marker. Equivalent to the NEW command. Does not require the BASIC window to be open or focused. The emulator must be powered on.
+
+**Get BASIC program content from editor:**
+```
+emma_command({ command: "saveBasicInEditorToLocal", params: {} })
+```
+Retrieves the BASIC program text from the editor. Returns the content as a string. Use with save_basic_file MCP tool to save to filesystem.
+
+**Get BASIC program content from memory:**
+```
+emma_command({ command: "directSaveBasicInMemoryToLocal", params: { path: "~/Documents/myprogram.bas" } })
+```
+Reads the BASIC program from emulator memory and returns the content. Use with save_basic_file MCP tool to save to filesystem.
+
+**Save BASIC program to filesystem (MCP tool):**
+```
+save_basic_file({ path: "~/Documents/myprogram.bas", content: "<program text>", overwrite: false })
+```
+Saves BASIC program text to a file on the local filesystem. Supports ~ for home directory. Set overwrite: true to replace existing files. Can be used with saveBasicInEditorToLocal (from editor) or directSaveBasicInMemoryToLocal (from memory) to get the content first.
+
+### Window Operations
+
+**Show the window:**
+```
+showWindow("basic-program")
+```
+
+**Hide the window:**
+```
+hideWindow("basic-program")
+```
+
+**Focus the window:**
+```
+focusWindow("basic-program")
+```
+
+### Editor Operations
+
+**Load BASIC program from memory:**
+```
+emma_command({ command: "basicProgramLoadFromMemory", params: {} })
+```
+Reads the tokenized BASIC program from emulator memory and displays it in the editor.
+
+**Load BASIC program into emulator:**
+```
+emma_command({ command: "basicProgramLoadIntoEmulator", params: {} })
+```
+Tokenizes the program in the editor and loads it into emulator memory. The emulator must be powered on for this to work.
+
+**Run BASIC program:**
+```
+emma_command({ command: "basicProgramRun", params: {} })
+```
+Execute the BASIC program in the emulator.
+
+**Pause BASIC program:**
+```
+emma_command({ command: "basicProgramPause", params: {} })
+```
+Pause BASIC program execution at the next statement.
+
+**New BASIC program (clear editor):**
+```
+emma_command({ command: "basicProgramNew", params: {} })
+```
+Clear all text from the BASIC program editor and start a new program.
+
+**Renumber BASIC program:**
+```
+emma_command({ command: "basicProgramRenumber", params: {} })
+```
+Renumber program lines in increments of 10, updating GOTO and GOSUB references.
+
+**Format BASIC program:**
+```
+emma_command({ command: "basicProgramFormat", params: {} })
+```
+Auto-format the BASIC code with proper alignment and indentation.
+
+**Get line and character count:**
+```
+emma_command({ command: "basicProgramLineCount", params: {} })
+```
+Returns the number of lines and characters in the editor.
+
+**Get current program:**
+```
+emma_command({ command: "basicProgramGet", params: {} })
+```
+Returns the current BASIC program text from the editor.
+
+**Edit program (find and replace):**
+```
+emma_command({ command: "basicProgramEdit", params: { oldText: "text to find", newText: "replacement text" } })
+```
+Find and replace specific text in the program.
+
+**Set program (replace all):**
+```
+emma_command({ command: "basicProgramSet", params: { program: "full program text" } })
+```
+Replace the entire program with new content.
+
+### Breakpoint and Debugging Operations
+
+**List all breakpoints:**
+```
+emma_command({ command: "basicProgramListBreakpoints", params: {} })
+```
+Returns an array of all breakpoints currently set, including line number, statement index, enabled state, and type (line or statement). Each breakpoint entry includes:
+- lineNumber: The BASIC line number
+- statementIndex: -1 for whole line, 0+ for specific statement
+- enabled: true if breakpoint is active
+- type: "line" for whole-line breakpoints, "statement" for statement-level breakpoints
+
+**Set a breakpoint on a BASIC line:**
+```
+emma_command({ command: "basicProgramSetBreakpoint", params: { lineNumber: 20 } })
+```
+Sets a whole-line breakpoint that will pause execution when that line is reached. Use lineNumber parameter to specify which line. Optional statementIndex parameter (default: -1 for whole line, 0+ for specific statement within a multi-statement line).
+
+**Remove a breakpoint:**
+```
+emma_command({ command: "basicProgramUnsetBreakpoint", params: { lineNumber: 20 } })
+```
+Removes a breakpoint from the specified line. Use lineNumber parameter to specify which line. Optional statementIndex parameter (default: -1 for whole line, 0+ for specific statement).
+
+**Step to next BASIC line:**
+```
+emma_command({ command: "basicProgramStepNext", params: {} })
+```
+When paused at a breakpoint, steps execution to the next BASIC line. Returns the previous and current line numbers. The emulator must be paused at a BASIC breakpoint for this to work. Clears the breakpoint hit flag and advances execution by one line.
+
+**Get current line number:**
+```
+emma_command({ command: "basicProgramGetCurrentLine", params: {} })
+```
+Returns the current BASIC line number if stopped at a breakpoint, or undefined if not stopped. Useful for checking execution state. Returns:
+- lineNumber: Current line number (or undefined if not at breakpoint)
+- message: Description of current state
+
+### Variable Inspection and Modification
+
+**Get all BASIC variables:**
+```
+emma_command({ command: "basicProgramGetVariables", params: {} })
+```
+Returns all BASIC variables currently in memory, including both simple variables and arrays. Each simple variable includes:
+- name: Variable name (e.g., "X", "A$", "COUNT%")
+- type: "real", "integer", or "string"
+- value: Raw value
+- formattedValue: Formatted for display
+
+Arrays include:
+- name: Array name
+- type: Variable type
+- dimensions: Array dimensions (e.g., [10] for single dimension, [5, 10] for two dimensions)
+- totalElements: Total number of elements
+- values: Flat array of all element values
+
+**Set a BASIC variable value:**
+```
+emma_command({ command: "basicProgramSetVariable", params: { name: "X", value: 42 } })
+```
+Sets a BASIC variable to a new value. The variable must already exist in memory (created by the running program). Parameters:
+- name: Variable name (e.g., "X", "A$", "COUNT%")
+- value: New value (number or string)
+
+Returns the old and new values. Works with:
+- Real numbers: `{ name: "X", value: 3.14 }`
+- Integers: `{ name: "COUNT%", value: 100 }`
+- Strings: `{ name: "A$", value: "HELLO" }` (quotes optional)
+
+Note: This modifies variables in place in memory. The program must have already declared the variable (e.g., via assignment).
+
+## Overview
+
+The basic-program window displays BASIC programs currently loaded in memory. It automatically detects whether the program is Applesoft BASIC or Integer BASIC and detokenizes it for viewing.
+
+
+## Features
+
+### Code Editor
+
+Large editable text area displaying the BASIC program with:
+- Line numbers automatically shown
+- Syntax highlighting for BASIC keywords
+- Full editing capabilities (type, copy/paste, edit)
+- Line and character count at bottom
+
+### Control Buttons
+
+**Run**: Execute the BASIC program in the emulator
+**Pause**: Pause program execution
+**Step**: Step through program line by line
+
+### Status Indicators
+
+- **IDLE**: Shows current execution state
+- **LINE**: Current line number being executed (--- when idle)
+- **PTR**: Memory pointer address ($---- when idle)
+
+### Variables Panel
+
+Right sidebar showing:
+- List of active BASIC variables and their current values
+- Shows "No variables" when program not running or no variables defined
+
+### Breakpoints Panel
+
+Right sidebar with tabs:
+- **Breakpoints**: Set line number breakpoints for debugging
+- **Line #**: Enter line number to break on
+- **+** button: Add breakpoint
+- Info button for breakpoint details
+- Shows "No breakpoints" when none are set
+
+### Action Buttons
+
+**Load from Memory**: Read BASIC program currently in emulator memory and display in editor
+**Load into Emulator**: Send program from editor into emulator memory
+**Format**: Auto-format the BASIC program
+**Renumber**: Renumber program lines (typically by 10s)
+**New**: Clear the editor and start a new program

package/public/docs/llms/llm-disk-drives.txt

@@ -0,0 +1,72 @@
+# Disk Drives
+
+> Floppy disk drive management for the Disk II controller (slot 6).
+
+## Tool Operations
+
+**Show the window:**
+```
+showWindow("disk-drives")
+```
+
+**Hide the window:**
+```
+hideWindow("disk-drives")
+```
+
+**Focus the window:**
+```
+focusWindow("disk-drives")
+```
+
+**Insert disk image by path:**
+```
+emma_command({ command: "driveInsertDisc", params: { driveNum: 1, path: "/path/to/disk.dsk" } })
+```
+Insert a disk image into drive 1 or 2 by providing a file path. The driveNum parameter defaults to 1 if not specified. The path can be a local filesystem path (with ~ expansion) or URL.
+
+**Get list of recent disks:**
+```
+emma_command({ command: "driveRecentsList", params: { driveNum: 1 } })
+```
+Get the list of recently used disks for drive 1 or 2. Returns an array of disk entries with filename and access time. The driveNum parameter defaults to 1 if not specified.
+
+**Clear recent disks:**
+```
+emma_command({ command: "drivesClearRecent", params: { driveNum: 1 } })
+```
+Clear all recent disks for drive 1 or 2. Removes all entries from the recent list for that drive. The driveNum parameter defaults to 1 if not specified.
+
+**Insert a recent disk:**
+```
+emma_command({ command: "driveInsertRecent", params: { driveNum: 1, name: "ProDOS_2_4_2.dsk" } })
+```
+Insert a disk from the recent disks list into drive 1 or 2. The name parameter must match a filename from the recent list. The driveNum parameter defaults to 1 if not specified.
+
+**Load a recent disk:**
+```
+emma_command({ command: "driveLoadRecent", params: { driveNum: 1, file: "ProDOS_2_4_2.dsk" } })
+```
+Load a disk from the recent disks list into drive 1 or 2. The file parameter must match a filename from the recent list. The driveNum parameter defaults to 1 if not specified.
+
+**Eject a disk:**
+```
+emma_command({ command: "diskDriveEject", params: { driveNum: 1 } })
+```
+Eject the disk from drive 1 or 2. Removes the disk image from the drive and updates the UI to show the drive as empty. The driveNum parameter defaults to 1 if not specified. If no disk is inserted, returns success with a message indicating the drive is already empty.
+
+## Overview
+
+The disk-drives window manages 5.25" floppy disk images for Drive 1 and Drive 2.
+
+## Supported Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| DSK | .dsk | Raw sector-order disk image (140KB). Most common format. DOS 3.3 logical order. |
+| DO | .do | Identical to DSK format. Extension explicitly indicates DOS 3.3 sector ordering. |
+| PO | .po | ProDOS-order disk image (140KB). Sectors in ProDOS physical order. |
+| NIB | .nib | Nibblised disk image (232,960 bytes). Raw GCR-encoded data as it appears on disk surface. |
+| WOZ | .woz | Bit-level disk image with timing and metadata. Most accurate format for copy-protected disks. |
+
+See /wiki/Disk-Drives.md for complete details on disk formats and operations.

package/public/docs/llms/llm-file-explorer.txt

@@ -0,0 +1,50 @@
+# File Explorer
+
+> Browse and read files from DOS 3.3 and ProDOS disk images.
+
+## Tool Operations
+
+**Show the window:**
+```
+showWindow("file-explorer-window")
+```
+
+**Hide the window:**
+```
+hideWindow("file-explorer-window")
+```
+
+**Focus the window:**
+```
+focusWindow("file-explorer-window")
+```
+
+**List files in a drive:**
+```
+emma_command({ command: "listDiskFiles", params: { drive: 0 } })
+```
+Lists all files on the disk in the specified drive (0 for drive 1, 1 for drive 2). Returns file catalog with filenames, types, sizes, and format (DOS 3.3 or ProDOS). Format the results as a table for the user, not as raw JSON.
+
+**Get file content from disk:**
+```
+emma_command({ command: "getDiskFileContent", params: { drive: 0, filename: "HELLO", isBinary: true } })
+```
+Reads a file from the disk. Set `isBinary: false` for text files to get plain text content, or `isBinary: true` (default) for binary files to get base64-encoded data. For ProDOS, can use full path like "SUBDIR/FILE". Text files (TXT, BAS) should use `isBinary: false`.
+
+**Save disk file to local filesystem (MCP tool):**
+```
+save_disk_file({ path: "~/Documents/file.bin", contentBase64: "<base64 data>", overwrite: false })
+```
+Saves file content to the local filesystem. Content must be base64 encoded (as returned by getDiskFileContent). Supports ~ for home directory.
+
+## Workflow Examples
+
+**Reading and displaying a text file:**
+1. List files: `listDiskFiles({ drive: 0 })`
+2. Get text content: `getDiskFileContent({ drive: 0, filename: "README", isBinary: false })`
+3. Display the `content` field directly to the user
+
+**Saving a binary file to local filesystem:**
+1. List files: `listDiskFiles({ drive: 0 })`
+2. Get binary content: `getDiskFileContent({ drive: 0, filename: "HELLO", isBinary: true })`
+3. Save locally: `save_disk_file({ path: "~/file.bin", contentBase64: result.contentBase64 })`

package/public/docs/llms/llm-hard-drives.txt

@@ -0,0 +1,80 @@
+# SmartPort Hard Drives
+
+> SmartPort hard drive image management for devices 1 and 2.
+
+## Tool Operations
+
+**Show the window:**
+```
+showWindow("hard-drives")
+```
+
+**Hide the window:**
+```
+hideWindow("hard-drives")
+```
+
+**Focus the window:**
+```
+focusWindow("hard-drives")
+```
+
+**List SmartPort-compatible slots:**
+```
+emma_command({ command: "smartportListSlots", params: {} })
+```
+Lists compatible expansion slots (2, 4, 5, 7) with current occupant and whether SmartPort is installed. Use this to find an available slot before installing.
+
+**Install SmartPort card into a slot:**
+```
+emma_command({ command: "smartportInstallCard", params: { slot: 7 } })
+```
+Installs the SmartPort card into the specified slot. Replaces any existing card in that slot. Triggers an emulator reset. Compatible slots: 2, 4, 5, 7. The SmartPort card must be installed before images can be loaded.
+
+**Insert SmartPort image by path:**
+```
+emma_command({ command: "smartportInsertImage", params: { deviceNum: 1, path: "/path/to/image.hdv" } })
+```
+Insert a SmartPort hard drive image into device 1 or 2 by providing a file path. The deviceNum parameter defaults to 1 if not specified.
+
+**Get list of recent images:**
+```
+emma_command({ command: "smartportRecentsList", params: { deviceNum: 1 } })
+```
+Get the list of recently used images for device 1 or 2. Returns an array of image entries with filename and access time. The deviceNum parameter defaults to 1 if not specified.
+
+**Insert a recent image:**
+```
+emma_command({ command: "smartportInsertRecent", params: { deviceNum: 1, name: "Total Replay.hdv" } })
+```
+Insert an image from the recent list into device 1 or 2. The name parameter must match a filename from the recent list. The deviceNum parameter defaults to 1 if not specified.
+
+**Clear recent images:**
+```
+emma_command({ command: "smartportClearRecent", params: { deviceNum: 1 } })
+```
+Clear all recent images for device 1 or 2. The deviceNum parameter defaults to 1 if not specified.
+
+**Eject a SmartPort image:**
+```
+emma_command({ command: "smartportEject", params: { deviceNum: 1 } })
+```
+Eject the hard drive image from device 1 or 2. Removes the image from the device and updates the UI to show the device as empty. The deviceNum parameter defaults to 1 if not specified. Requires the SmartPort card to be installed.
+
+**Load SmartPort image from filesystem (MCP tool):**
+```
+load_smartport_image({ path: "~/images/prodos.hdv" })
+```
+Load a SmartPort image file from the local filesystem and return as base64. Supports ~ for home directory.
+
+## Supported Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| HDV | .hdv | Raw block device image. Most common SmartPort format. |
+| PO | .po | ProDOS-order block image. |
+| 2IMG | .2mg | Universal disk image with metadata header. |
+
+## Notes
+
+The SmartPort card must be installed in a compatible expansion slot before images can be loaded. Use `smartportListSlots` to check, and `smartportInstallCard` to install if needed. Installing or changing slot configuration triggers an emulator reset.