web-a2e 1.0.0

package/wiki/Expansion-Slots.md

@@ -0,0 +1,187 @@
+# Expansion Slots
+
+The Apple IIe has seven expansion slots (1-7), each providing I/O space and ROM space for peripheral cards. The emulator supports a configurable set of expansion cards that can be installed in their compatible slots.
+
+## Table of Contents
+
+- [Slot Map](#slot-map)
+- [Configuring Slots](#configuring-slots)
+- [Available Cards](#available-cards)
+- [Memory Map](#memory-map)
+- [Card Interface](#card-interface)
+
+## Slot Map
+
+The default slot configuration matches a typical Apple IIe setup:
+
+| Slot | Default Card | Description |
+|------|-------------|-------------|
+| 1 | Empty | Printer / Serial |
+| 2 | Empty | Serial / Modem |
+| 3 | 80-Column (Built-in) | Fixed -- cannot be changed |
+| 4 | Mockingboard | Sound cards / Mouse |
+| 5 | Empty | Clock / Hard drive |
+| 6 | Disk II Controller | Disk drives |
+| 7 | Thunderclock Plus | RAM disk / Clock |
+
+## Configuring Slots
+
+Open the **Expansion Slots** window from the **System** menu to change which cards are installed in each slot.
+
+### How It Works
+
+Each configurable slot has a dropdown menu listing the cards that are compatible with that slot. Select a card from the dropdown, and a warning will appear indicating that changes require a reset. Click **Apply & Reset** to apply all pending changes and restart the emulator.
+
+### Slot Restrictions
+
+- **Slot 3** is fixed and always contains the built-in 80-column firmware. It cannot be changed.
+- Each card type can only be installed in one slot at a time. If a card is already in use in another slot, its option will be grayed out in the dropdown.
+- Not all cards are available in all slots. Each slot has a specific list of compatible cards based on Apple II conventions.
+
+### Compatible Cards per Slot
+
+| Slot | Available Cards |
+|------|----------------|
+| 1 | Empty |
+| 2 | Empty |
+| 3 | 80-Column (fixed) |
+| 4 | Empty, Mockingboard, Apple Mouse Card |
+| 5 | Empty, Thunderclock Plus |
+| 6 | Empty, Disk II Controller |
+| 7 | Empty, Thunderclock Plus |
+
+### Persistence
+
+Slot configuration is saved to localStorage and automatically restored when the emulator is loaded. If no saved configuration exists, the default card assignments shown in the Slot Map above are used.
+
+## Available Cards
+
+### Disk II Controller
+
+The Disk II controller card provides access to two 5.25-inch floppy disk drives. It uses 16 soft switches in the I/O space for drive control including phase stepping, motor control, drive selection, and read/write operations.
+
+- **Default slot:** 6
+- **I/O space:** `$C0E0`-`$C0EF` (16 soft switches)
+- **ROM space:** `$C600`-`$C6FF` (256-byte bootstrap ROM, P5A 341-0027)
+- **Supported formats:** DSK, DO, PO, NIB, WOZ
+
+Soft switch layout:
+
+| Offset | Even (Off) | Odd (On) |
+|--------|-----------|----------|
+| $00-$01 | Phase 0 off | Phase 0 on |
+| $02-$03 | Phase 1 off | Phase 1 on |
+| $04-$05 | Phase 2 off | Phase 2 on |
+| $06-$07 | Phase 3 off | Phase 3 on |
+| $08-$09 | Motor off | Motor on |
+| $0A-$0B | Drive 1 select | Drive 2 select |
+| $0C-$0D | Q6L (read) | Q6H (write protect / write load) |
+| $0E-$0F | Q7L (read mode) | Q7H (write mode) |
+
+See [[Disk-Drives]] for more details on disk operation.
+
+### Mockingboard
+
+The Mockingboard sound card provides stereo audio through two AY-3-8910 Programmable Sound Generator (PSG) chips, each controlled by a MOS 6522 Versatile Interface Adapter (VIA). It was the most popular sound card for the Apple II.
+
+- **Default slot:** 4
+- **ROM space:** `$C400`-`$C4FF` (VIA registers -- unusual; most cards use I/O space)
+- **VIA 1:** `$C400`-`$C47F` (bit 7 = 0) -- controls left channel PSG
+- **VIA 2:** `$C480`-`$C4FF` (bit 7 = 1) -- controls right channel PSG
+
+The Mockingboard is unusual among Apple II cards in that it uses the slot ROM address space for its VIA registers instead of the I/O space, because it needs more than the 16 bytes available in the I/O range.
+
+Each PSG provides 3 tone channels and 1 noise channel, for a total of 6 tone channels and 2 noise channels in stereo.
+
+See [[Audio-System]] for more details on Mockingboard audio.
+
+### Thunderclock Plus
+
+The Thunderclock Plus is a ProDOS-compatible real-time clock card. It provides automatic date and time stamping for ProDOS applications, eliminating manual date entry prompts and enabling proper file timestamps.
+
+- **Compatible slots:** 5, 7
+- **Default slot:** 7
+- **I/O space:** Control register at `$C0n0`
+- **ROM space:** `$Cn00`-`$CnFF` (256-byte ProDOS clock driver)
+- **Expansion ROM:** `$C800`-`$CFFF` (utility routines)
+
+The Thunderclock uses the host system's real date and time, so ProDOS file timestamps will reflect the actual current time.
+
+**ProDOS detection:** ProDOS scans expansion slot ROM looking for specific signature bytes (`$08`, `$28`, `$58`, `$70` at offsets 0, 2, 4, 6). When found, ProDOS patches its clock driver to use the Thunderclock for all date/time operations.
+
+**Hardware interface:** The card uses a serial interface based on the NEC uPD1990C clock chip. Time data is transmitted as 40 bits (10 BCD nibbles) encoding seconds, minutes, hours, day, day-of-week, and month.
+
+### Apple Mouse Card
+
+The Apple Mouse Interface Card provides mouse input for Apple II software. It emulates the MC6821 PIA-based command protocol used by the original card's firmware.
+
+- **Compatible slots:** 4 (shares with Mockingboard)
+- **I/O space:** `$C0n0`-`$C0n3` (MC6821 PIA registers)
+- **ROM space:** `$Cn00`-`$CnFF` (firmware)
+- **Expansion ROM:** Full 2 KB ROM with page selection via Port B bits 1-3
+
+The mouse card firmware runs as native 6502 code on the CPU. The emulator provides the hardware-side emulation of the MC6821 PIA, receiving commands from the firmware and providing mouse position and button data.
+
+**VBL interrupt support:** When the mouse mode has bit 3 set, an IRQ is generated at the start of each vertical blanking period, allowing software to poll the mouse at a consistent 60 Hz rate.
+
+## Memory Map
+
+Each expansion slot is assigned dedicated address ranges in the Apple IIe memory map:
+
+### I/O Space ($C080-$C0FF)
+
+Each slot gets 16 bytes of I/O space. Software reads and writes to these addresses to communicate with the card's hardware.
+
+| Slot | I/O Range |
+|------|-----------|
+| 1 | `$C090`-`$C09F` |
+| 2 | `$C0A0`-`$C0AF` |
+| 3 | `$C0B0`-`$C0BF` |
+| 4 | `$C0C0`-`$C0CF` |
+| 5 | `$C0D0`-`$C0DF` |
+| 6 | `$C0E0`-`$C0EF` |
+| 7 | `$C0F0`-`$C0FF` |
+
+### Slot ROM Space ($C100-$C7FF)
+
+Each slot gets 256 bytes of ROM space. When the CPU reads from this range, the card in that slot provides the data. This is typically used for identification bytes, bootstrap code, or (in the Mockingboard's case) hardware register access.
+
+| Slot | ROM Range |
+|------|-----------|
+| 1 | `$C100`-`$C1FF` |
+| 2 | `$C200`-`$C2FF` |
+| 3 | `$C300`-`$C3FF` |
+| 4 | `$C400`-`$C4FF` |
+| 5 | `$C500`-`$C5FF` |
+| 6 | `$C600`-`$C6FF` |
+| 7 | `$C700`-`$C7FF` |
+
+### Expansion ROM Space ($C800-$CFFF)
+
+A shared 2 KB region that can be mapped to any card's expansion ROM. When the CPU accesses a card's slot ROM, that card's expansion ROM (if it has one) becomes active in this shared range. Cards like the Thunderclock and Mouse Card use this for additional firmware.
+
+### ROM Switching Soft Switches
+
+Two soft switches control how the slot ROM area is accessed:
+
+- **INTCXROM** (`$C006`/`$C007`) -- When set, the internal ROM is used for the entire `$C100`-`$CFFF` range instead of slot ROMs.
+- **SLOTC3ROM** (`$C00A`/`$C00B`) -- When set, slot 3 uses the card's ROM instead of the built-in 80-column firmware.
+
+## Card Interface
+
+All expansion cards implement the `ExpansionCard` interface, which provides the following methods:
+
+| Method | Description |
+|--------|-------------|
+| `readIO(offset)` | Read from the card's I/O space (offset 0-15) |
+| `writeIO(offset, value)` | Write to the card's I/O space |
+| `readROM(offset)` | Read from the card's ROM space (offset 0-255) |
+| `writeROM(offset, value)` | Write to the card's ROM space (unusual, used by Mockingboard) |
+| `readExpansionROM(offset)` | Read from expansion ROM (offset 0-2047) |
+| `reset()` | Reset the card to power-on state |
+| `update(cycles)` | Update card state each CPU cycle |
+| `serialize() / deserialize()` | Save and restore card state |
+
+Cards can also generate IRQ interrupts via a callback mechanism, used by the Mockingboard's VIA timers and the Mouse Card's VBL interrupt.
+
+See also: [[Architecture-Overview]], [[Audio-System]], [[Disk-Drives]]

package/wiki/File-Explorer.md

@@ -0,0 +1,259 @@
+# File Explorer
+
+The File Explorer provides a built-in disk image browser that can read and display files stored on DOS 3.3 and ProDOS formatted disk images. It supports viewing Applesoft BASIC, Integer BASIC, text files, binary files (with disassembly), hex dumps, and Merlin assembler source code.
+
+## Table of Contents
+
+- [Opening the File Explorer](#opening-the-file-explorer)
+- [Interface Layout](#interface-layout)
+- [Supported Disk Formats](#supported-disk-formats)
+- [Browsing Files](#browsing-files)
+- [File Types](#file-types)
+- [View Modes](#view-modes)
+- [BASIC Program Viewer](#basic-program-viewer)
+- [Disassembler](#disassembler)
+- [Hex Dump](#hex-dump)
+- [Merlin Assembler Source](#merlin-assembler-source)
+- [Text Files](#text-files)
+
+## Opening the File Explorer
+
+Open the File Explorer from the **Tools** menu. When the window opens, it automatically reads the disk currently inserted in the selected drive.
+
+## Interface Layout
+
+The File Explorer window is divided into three areas:
+
+### Toolbar
+
+The toolbar at the top contains:
+
+- **Drive selector** -- Toggle between Drive 1 and Drive 2 to browse disks in either drive
+- **Refresh button** -- Re-reads the current disk catalog (useful after the emulator modifies the disk)
+- **Disk info** -- Displays the disk filename and detected format (e.g. `MyDisk.dsk (DOS 3.3)` or `Utils.po (ProDOS: UTILITIES)`)
+
+### Catalog Panel (Left)
+
+The left panel shows the file listing for the current disk. Each entry displays:
+
+- **File type** -- A short type code (`A` for Applesoft, `B` for Binary, `T` for Text, etc.)
+- **Filename** -- The file's name as stored on disk
+- **Size** -- Sector count (DOS 3.3) or block count (ProDOS)
+- **Lock indicator** -- An asterisk (`*`) appears before the type code if the file is locked
+
+For ProDOS disks, directories are shown with a `DIR` type indicator and a trailing `/` on the name. Clicking a directory navigates into it.
+
+### File Viewer Panel (Right)
+
+The right panel displays the contents of the currently selected file. The header shows the filename, file type description, and file size. View mode toggle buttons appear when applicable (e.g. Disassemble / HEX / MERLIN for binary files).
+
+## Supported Disk Formats
+
+The File Explorer supports two Apple II disk operating systems:
+
+### DOS 3.3
+
+Standard Apple II disk format with 35 tracks, 16 sectors per track (143,360 bytes). The explorer reads the Volume Table of Contents (VTOC) at track 17, sector 0 and follows the catalog sector chain to list all files.
+
+**Recognized DOS 3.3 file types:**
+
+| Type Code | Hex | Description |
+|-----------|-----|-------------|
+| T | $00 | Text file |
+| I | $01 | Integer BASIC program |
+| A | $02 | Applesoft BASIC program |
+| B | $04 | Binary file |
+| S | $08 | Type S |
+| R | $10 | Relocatable object |
+| a | $20 | Type a |
+| b | $40 | Type b |
+
+### ProDOS
+
+Apple's more advanced disk operating system with hierarchical directory support. The explorer reads the volume directory starting at block 2 and recursively scans all subdirectories.
+
+**Recognized ProDOS file types:**
+
+| Type Code | Hex  | Description |
+|-----------|------|-------------|
+| TXT | $04 | Text file |
+| BIN | $06 | Binary file |
+| DIR | $0F | Directory |
+| ADB | $19 | AppleWorks Database |
+| AWP | $1A | AppleWorks Word Processor |
+| ASP | $1B | AppleWorks Spreadsheet |
+| SRC | $B0 | Source Code |
+| S16 | $B3 | GS/OS Application |
+| DOC | $BF | Document |
+| PNT | $C0 | Packed HiRes |
+| PIC | $C1 | HiRes Picture |
+| SHK | $E0 | ShrinkIt Archive |
+| PAS | $EF | Pascal |
+| CMD | $F0 | Command |
+| INT | $FA | Integer BASIC program |
+| IVR | $FB | Integer BASIC Variables |
+| BAS | $FC | Applesoft BASIC program |
+| VAR | $FD | Applesoft Variables |
+| REL | $FE | Relocatable object |
+| SYS | $FF | System file |
+
+### ProDOS Directory Navigation
+
+When browsing a ProDOS disk, the File Explorer provides full directory navigation:
+
+- **Breadcrumb path bar** -- Appears when inside a subdirectory, showing the full path with clickable segments (e.g. `/UTILITIES/SYSTEM`). Click any path component to jump directly to that directory.
+- **Parent directory entry** (`..`) -- Shown at the top of the file list when inside a subdirectory. Click to go up one level.
+- **Directories** -- Displayed with a `DIR` type label and a trailing slash. Click to enter the directory.
+
+Files are sorted with directories listed first, then files, both in alphabetical order.
+
+## File Types
+
+The File Explorer automatically selects the appropriate viewer based on the file type:
+
+| File Type | Viewer |
+|-----------|--------|
+| Applesoft BASIC | Syntax-highlighted BASIC listing with navigable line references |
+| Integer BASIC | Syntax-highlighted BASIC listing with navigable line references |
+| Text | Plain text display (with optional Merlin detection) |
+| Binary | Disassembly view with hex and Merlin alternatives |
+| System (ProDOS SYS) | Disassembly view with hex and Merlin alternatives |
+| All other types | Hex dump |
+
+## View Modes
+
+### Binary File View Modes
+
+When viewing a binary file (DOS 3.3 type `B`, ProDOS types `BIN` or `SYS`), three view mode buttons appear:
+
+- **Disassemble** -- 65C02 disassembly with flow analysis (default)
+- **HEX** -- Color-coded hex dump with ASCII sidebar
+- **MERLIN** -- Merlin assembler source view (auto-selected when Merlin source is detected)
+
+### Text File View Modes
+
+When viewing a text file, two view mode buttons appear:
+
+- **TEXT** -- Plain text display (default)
+- **MERLIN** -- Merlin assembler source view (auto-selected when Merlin source is detected)
+
+## BASIC Program Viewer
+
+BASIC programs (Applesoft and Integer BASIC) are detokenized using the emulator's C++ BASIC detokenizer (via WASM) and then rendered with syntax highlighting.
+
+### Syntax Highlighting
+
+BASIC listings use color-coded highlighting for different language elements:
+
+- Line numbers
+- Keywords (PRINT, FOR, NEXT, IF, THEN, etc.)
+- Strings
+- Numbers
+- Operators
+- Comments (REM statements)
+
+### Line Navigation
+
+GOTO, GOSUB, and THEN targets are rendered as clickable references. Clicking a line number reference in a GOTO or GOSUB statement scrolls to and highlights the target line in the listing. The target line is centered in the view and highlighted for easy identification.
+
+## Disassembler
+
+The disassembler provides a 65C02 disassembly view for binary and system files. It uses the emulator's C++ disassembler core with recursive-descent flow analysis to distinguish code from data.
+
+### Features
+
+- **Flow analysis** -- Uses recursive descent from the entry point to trace execution paths through branches and jumps, distinguishing actual code from embedded data
+- **ORG directive** -- Shows the load address at the top of the listing
+- **Data gaps** -- Bytes not reached by flow analysis are displayed as `.BYTE` data directives (up to 8 bytes per line)
+- **Color-coded instruction categories:**
+  - Jump/Branch (JMP, JSR, BNE, etc.)
+  - Load/Store (LDA, STA, LDX, etc.)
+  - Math/Logic (ADC, AND, ORA, etc.)
+  - Stack/Register (PHA, TAX, etc.)
+  - Addresses and immediates
+  - Data bytes
+
+A color legend is displayed above the listing.
+
+### Clickable Branch Targets
+
+Branch and jump target addresses are clickable. Clicking a target scrolls to and highlights the destination instruction. This works for both relative branches (BNE, BEQ, etc.) and absolute jumps (JMP, JSR).
+
+### Virtual Scrolling
+
+For large binary files (500+ disassembled lines), the disassembler uses virtual scrolling to maintain smooth performance. Only the visible portion of the listing is rendered at any time, with a small buffer above and below the viewport.
+
+### Address Format
+
+Each line shows the address, raw bytes, mnemonic, and operand:
+
+```
+ORG   $0800
+0800: A9 00     LDA #$00
+0802: 8D 00 20  STA $2000
+0805: 4C 00 08  JMP $0800
+```
+
+DOS 3.3 binary files include a 4-byte header (2 bytes load address, 2 bytes length) that is automatically parsed to determine the base address. ProDOS binary files store the load address in the file entry's auxiliary type field.
+
+## Hex Dump
+
+The hex dump view displays raw file data with color coding and an ASCII sidebar.
+
+### Color Coding
+
+Bytes are color-coded by category with a legend displayed above the view:
+
+- **Printable** -- Standard ASCII characters ($20-$7E)
+- **Control** -- Control characters ($01-$1F)
+- **High Bit** -- Bytes with the high bit set ($80-$FF)
+- **Zero** -- Null bytes ($00)
+
+### Layout
+
+Each line shows:
+
+```
+ADDR: XX XX XX XX XX XX XX XX  XX XX XX XX XX XX XX XX  |ASCII display...|
+```
+
+- **Address** -- 4-digit hex address
+- **Hex bytes** -- Bytes displayed in groups of 8, separated by a gap
+- **ASCII sidebar** -- Printable characters shown as-is (with high bit stripped), non-printable shown as dots
+
+### Dynamic Column Count
+
+The hex dump automatically adjusts the number of bytes displayed per row based on the window width. Resizing the File Explorer window dynamically recalculates the optimal column count to fill the available space.
+
+## Merlin Assembler Source
+
+The File Explorer can detect and display Merlin assembler source files with full syntax highlighting. Merlin was the most popular macro assembler for the Apple II.
+
+### Auto-Detection
+
+When a binary or text file is selected, the explorer automatically checks whether the content looks like Merlin assembler source. If detected, the view mode automatically switches to the MERLIN view. You can manually switch between views using the toggle buttons.
+
+### Syntax Highlighting
+
+Merlin source files are displayed with syntax highlighting that matches the disassembler's color scheme:
+
+- **Jump/Branch mnemonics** -- JMP, JSR, BNE, BCC, RTS, etc.
+- **Load/Store mnemonics** -- LDA, STA, LDX, STY, etc.
+- **Math/Logic mnemonics** -- ADC, AND, ORA, ASL, CMP, etc.
+- **Stack/Register mnemonics** -- PHA, PLA, TAX, TXA, etc.
+- **Flag mnemonics** -- CLC, SEC, SEI, NOP, etc.
+- **Directives** -- ORG, EQU, DS, DFB, ASC, HEX, PUT, MAC, and many more
+- **Labels** -- Symbols defined at the start of lines
+- **Comments** -- Text following semicolons or asterisks
+- **Addresses and values** -- Hex values and numeric constants
+
+## Text Files
+
+Text files are displayed with Apple II character encoding properly handled:
+
+- High-bit stripping (Apple II text uses $80-$FF for normal characters)
+- Carriage return ($0D) conversion to newlines
+- Tab ($09) preservation
+- Null byte ($00) filtering
+
+See also: [[Disk-Drives]], [[Getting-Started]]

package/wiki/Getting-Started.md

@@ -0,0 +1,156 @@
+# Getting Started
+
+This guide walks you through your first session with the Apple //e Emulator -- from opening the page to running software.
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Opening the Emulator](#opening-the-emulator)
+- [Powering On](#powering-on)
+- [The Toolbar](#the-toolbar)
+- [Using the Keyboard](#using-the-keyboard)
+- [Inserting a Disk](#inserting-a-disk)
+- [Pasting Text](#pasting-text)
+- [Copying Screen Text](#copying-screen-text)
+- [Full-Page Mode](#full-page-mode)
+- [Installing as a PWA](#installing-as-a-pwa)
+- [Themes](#themes)
+- [Getting Help](#getting-help)
+
+---
+
+## Requirements
+
+The emulator runs in any modern browser that supports WebAssembly, WebGL, and the Web Audio API:
+
+- Chrome / Edge (recommended)
+- Firefox
+- Safari
+
+No downloads, plugins, or accounts are needed. The emulator loads entirely in the browser.
+
+## Opening the Emulator
+
+Navigate to the emulator URL. A loading spinner appears while the WebAssembly core initialises. Once ready, the screen shows TV static (the "no signal" pattern), indicating the virtual Apple //e is powered off.
+
+A floating reminder will point to the power button for first-time visitors.
+
+## Powering On
+
+Click the **Power** button (the circle-with-a-line icon) in the top-left area of the toolbar. The button changes colour to indicate the machine is on, and the screen will display the Apple IIe boot sequence.
+
+- If a **disk is inserted**, the Disk II controller will attempt to boot from it.
+- If **no disk** is present, the screen shows a checksum test. A reminder will suggest pressing **Ctrl+Reset** to drop into Applesoft BASIC.
+
+### Reset Options
+
+| Button | Action |
+|--------|--------|
+| **Ctrl+Reset** | Warm reset -- preserves memory contents, re-enters the monitor or BASIC prompt |
+| **Reboot** | Cold reset -- full power-cycle restart, clears all state |
+
+Both buttons are in the toolbar next to the power button.
+
+## The Toolbar
+
+The toolbar along the top of the page provides access to all emulator functions:
+
+| Control | Purpose |
+|---------|---------|
+| **Power** | Turn the emulated Apple //e on or off |
+| **Ctrl+Reset** | Warm reset (preserves memory) |
+| **Reboot** | Cold reset (full restart) |
+| **File** | Auto-save toggle, save states manager |
+| **View** | Theme selector, Disk Drives, File Explorer, Display settings, Joystick/Paddles, Expansion Slots |
+| **Debug** | CPU Debugger, Soft Switches, Memory Map, Memory Browser, Heat Map, Stack Viewer, Zero Page Watch, Mockingboard, Mouse Card |
+| **Dev** | Applesoft BASIC editor, 6502 Assembler |
+| **Full Page** | Expand the screen to fill the browser window |
+| **Sound** | Volume slider, mute toggle, drive sounds toggle |
+| **Help** | Documentation (F1), Release Notes, Check for Updates |
+
+## Using the Keyboard
+
+Click the emulator screen to give it keyboard focus. Once focused, key presses are sent directly to the emulated Apple //e. The C++ core translates browser key codes to Apple II key codes, handling Shift, Ctrl, and Caps Lock modifiers.
+
+Key points:
+
+- **Arrow keys** work as expected in software that supports them (the Apple //e has native arrow key support).
+- **Backspace** sends the Apple II left-arrow (delete) key.
+- **Tab** is captured by the emulator and not passed to the browser.
+- **Escape** sends the Apple II ESC key.
+- **Ctrl+key** combinations pass through to the emulator (e.g., Ctrl+C, Ctrl+D for DOS commands).
+- **Browser shortcuts** like Ctrl+R (reload) are not intercepted and work normally.
+
+For the full shortcut reference see [[Keyboard-Shortcuts]].
+
+## Inserting a Disk
+
+1. Open **View > Disk Drives** from the toolbar (or use the window switcher with Ctrl+\`).
+2. The Disk Drives window shows Drive 1 and Drive 2.
+3. **Drag and drop** a disk image file onto a drive slot, or click the drive's **Load** button to browse for a file.
+4. Supported formats: **DSK**, **DO**, **PO**, **NIB**, and **WOZ**.
+5. If the emulator is running, the disk will begin spinning and the Apple //e will detect it.
+
+To boot from a newly inserted disk, press **Ctrl+Reset** or click **Reboot**.
+
+See [[Disk-Drives]] for full details on disk management, write protection, surface visualisation, and drive sounds.
+
+## Pasting Text
+
+Press **Ctrl+V** while the emulator screen has focus to paste text from the clipboard. The emulator:
+
+1. Reads the clipboard contents.
+2. Converts each character to its Apple II key equivalent.
+3. Feeds the characters into the emulated keyboard at 8x speed (the emulation temporarily accelerates to process paste quickly).
+4. Automatically waits for the keyboard-ready flag between characters to avoid dropped input.
+
+This is useful for entering BASIC programs or long commands. Paste is cancelled automatically if you press Ctrl+Reset or Reboot during the operation.
+
+## Copying Screen Text
+
+You can select and copy text directly from the Apple //e screen:
+
+1. **Click and drag** on the emulator screen to highlight text.
+2. The selection is shown as a coloured overlay.
+3. Press **Ctrl+C** (or Cmd+C on Mac) to copy the selected text to the clipboard.
+4. The selection works in both 40-column and 80-column text modes.
+
+## Full-Page Mode
+
+Click the **Full Page** button (expand icon) in the toolbar to fill the entire browser window with the emulator screen. This hides the toolbar and footer for a distraction-free experience.
+
+While in full-page mode:
+
+- Move the mouse to the **top of the screen** to reveal a floating toolbar with Power, Ctrl+Reset, Reboot, and Exit controls.
+- Press **Ctrl+Escape** to exit full-page mode and return to the normal view.
+
+## Installing as a PWA
+
+The emulator can be installed as a Progressive Web App for a more native experience:
+
+1. Open the emulator in Chrome or Edge.
+2. Click the install icon in the browser address bar (or use the browser menu).
+3. The emulator will open in its own window without browser chrome.
+
+The PWA manifest provides the app title "Apple //e" with appropriate icons.
+
+## Themes
+
+The emulator supports three themes, selectable from **View > Theme**:
+
+| Theme | Description |
+|-------|-------------|
+| **Light** | Light background with dark text for toolbar and windows |
+| **Dark** | Dark background (default) suited for extended use |
+| **System** | Automatically follows your operating system's light/dark preference |
+
+The theme applies to the toolbar, all debug windows, dialogs, and settings panels. The emulator screen itself is unaffected -- it always renders authentic Apple II colours.
+
+## Getting Help
+
+- Press **F1** at any time to open the built-in Documentation window.
+- Open **Help > Release Notes** to see what has changed in the current version.
+- Open **Help > Check for Updates** to see if a newer version is available.
+- The footer bar at the bottom of the page also links to Release Notes and shows the F1 hint.

package/wiki/Home.md

@@ -0,0 +1,69 @@
+# Apple //e Emulator
+
+A cycle-accurate Apple II Enhanced emulator running entirely in the browser. Built with WebAssembly (C++ backend) and WebGL rendering, it faithfully reproduces the 1MHz 65C02 processor, 128KB memory architecture, all standard video modes, Disk II controller, expansion cards, and speaker audio -- no plugins or installs required.
+
+---
+
+## Feature Highlights
+
+- **Cycle-accurate 65C02 CPU** at 1.023 MHz with full NMOS 6502 and 65C02 extended opcode support
+- **128KB memory** (64KB main + 64KB auxiliary) with Language Card and double hi-res capability
+- **All Apple IIe video modes** -- Text, Lo-Res, Hi-Res, Double Hi-Res, Double Lo-Res, and 80-column text
+- **CRT shader effects** -- scanlines, phosphor glow, screen curvature, chromatic aberration, vignette, and analog noise via WebGL
+- **Disk II emulation** with DSK, DO, PO, and WOZ format support and real-time surface visualization
+- **Expansion card system** -- Mockingboard (dual AY-3-8910), Thunderclock Plus, Mouse Interface Card
+- **Audio-driven timing** using Web Audio API at 48 kHz for accurate, drift-free emulation even when backgrounded
+- **Save states** -- autosave plus five manual slots stored in IndexedDB
+- **Built-in debugger suite** -- CPU debugger, memory browser, heat map, stack viewer, soft switch monitor, and more
+- **Applesoft BASIC editor** and **6502 assembler** with direct memory injection
+- **File Explorer** for browsing DOS 3.3 and ProDOS disk contents
+- **Installable PWA** with light, dark, and system-follow themes
+- **Paste support** (Ctrl+V) and full-page mode
+
+## Quick Start
+
+1. Open the emulator in a modern browser (Chrome, Firefox, Safari, or Edge).
+2. Click the **Power** button in the toolbar to turn on the Apple //e.
+3. If no disk is inserted you will see the Applesoft BASIC prompt after pressing **Ctrl+Reset**.
+4. To load software, open **View > Disk Drives**, drag a disk image onto a drive slot or click **Load** to browse.
+5. Press **F1** at any time for built-in documentation.
+
+See [[Getting-Started]] for a full walkthrough.
+
+---
+
+## Wiki Contents
+
+### User Guide
+
+| Page                   | Description                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------ |
+| [[Getting-Started]]    | First-time setup, powering on, inserting disks, keyboard basics, paste, and full-page mode |
+| [[Display-Settings]]   | CRT effects, analog noise, image controls, colour modes, and rendering options             |
+| [[Disk-Drives]]        | Disk formats, drive UI, surface visualization, write protection, and drive sounds          |
+| [[File-Explorer]]      | Browsing DOS 3.3 and ProDOS disk contents, viewing files, and disassembly                  |
+| [[Save-States]]        | Autosave, manual save slots, and state management                                          |
+| [[Expansion-Slots]]    | Slot configuration, Mockingboard, Thunderclock, Mouse Card                                 |
+| [[Input-Devices]]      | Keyboard mapping, joystick/paddle configuration, mouse support                             |
+| [[AI-Agent]]           | LLM integration via MCP, connection status, server setup, and example prompts              |
+| [[Keyboard-Shortcuts]] | Complete keyboard shortcut reference                                                       |
+
+### Developer Guide
+
+| Page                      | Description                                                              |
+| ------------------------- | ------------------------------------------------------------------------ |
+| [[Architecture-Overview]] | Two-layer design, audio-driven timing, WASM interface pattern            |
+| [[CPU-Emulation]]         | 65C02 implementation, cycle accuracy, Klaus Dormann test compliance      |
+| [[Memory-System]]         | MMU soft switches, Language Card, bank switching, auxiliary memory       |
+| [[Video-Rendering]]       | Scanline rendering, WebGL pipeline, CRT shader architecture              |
+| [[Audio-System]]          | Speaker toggle emulation, Mockingboard synthesis, AudioWorklet pipeline  |
+| [[Disk-System-Internals]] | GCR encoding, WOZ format handling, Disk II controller state machine      |
+| [[Debugger]]              | CPU debugger, breakpoints, rule builder, memory tools, and debug windows |
+
+---
+
+## Version
+
+Current release: **1.5.0**
+
+Open **Help > Release Notes** inside the emulator to see what's new.