web-a2e 1.0.0

package/wiki/Debugger.md

@@ -0,0 +1,516 @@
+# Debugger
+
+The emulator includes a comprehensive suite of debug windows accessible via the Debug menu. These tools provide deep visibility into the CPU state, memory contents, peripheral hardware, and BASIC program execution.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [CPU Debugger](#cpu-debugger)
+  - [Toolbar and Execution Control](#toolbar-and-execution-control)
+  - [Register Display](#register-display)
+  - [Disassembly View](#disassembly-view)
+  - [Breakpoints](#breakpoints)
+  - [Watchpoints](#watchpoints)
+  - [Watch Expressions](#watch-expressions)
+  - [Beam Breakpoints](#beam-breakpoints)
+  - [Bookmarks](#bookmarks)
+  - [Symbol Resolution](#symbol-resolution)
+  - [User Labels](#user-labels)
+- [Memory Browser](#memory-browser)
+- [Memory Heat Map](#memory-heat-map)
+- [Memory Map](#memory-map)
+- [Stack Viewer](#stack-viewer)
+- [Zero Page Watch](#zero-page-watch)
+- [Soft Switch Monitor](#soft-switch-monitor)
+- [Mockingboard Debug](#mockingboard-debug)
+- [Mouse Card Debug](#mouse-card-debug)
+- [BASIC Program Window](#basic-program-window)
+  - [Editor](#editor)
+  - [BASIC Debugger](#basic-debugger)
+  - [Variable Inspector](#variable-inspector)
+  - [BASIC Breakpoints](#basic-breakpoints)
+- [Rule Builder](#rule-builder)
+- [Assembler Editor](#assembler-editor)
+- [Instruction Trace](#instruction-trace)
+- [Keyboard Shortcuts](#keyboard-shortcuts)
+- [Source Files](#source-files)
+
+---
+
+## Overview
+
+All debug windows extend the `BaseWindow` class from the window manager system. They share common behaviors: draggable/resizable chrome, persistence of position and size via localStorage, and automatic refresh when the emulator is paused or single-stepping.
+
+Debug windows are organized into categories:
+
+| Category | Windows |
+|----------|---------|
+| CPU & Memory | CPU Debugger, Memory Browser, Memory Heat Map, Memory Map, Stack Viewer, Zero Page Watch |
+| Hardware | Soft Switch Monitor, Mockingboard, Mouse Card |
+| Programming | BASIC Program Window, Assembler Editor |
+| Tools | Rule Builder, Instruction Trace |
+
+---
+
+## CPU Debugger
+
+The CPU Debugger (`cpu-debugger-window.js`) is the primary debug tool, providing register inspection, disassembly, breakpoint management, and stepping controls.
+
+### Toolbar and Execution Control
+
+The toolbar provides:
+
+- **Run** (F5): Resume execution from the current PC
+- **Pause**: Break execution at the current instruction
+- **Step Into** (F11): Execute a single instruction
+- **Step Over** (F10): Execute the current instruction; if it is a JSR, run until the subroutine returns
+- **Step Out** (Shift+F11): Run until the current subroutine returns (RTS/RTI)
+- **Status indicator**: Shows RUNNING or PAUSED state
+
+### Register Display
+
+The register section shows the current CPU state organized into groups:
+
+**REGS section:**
+- A, X, Y registers (8-bit hex)
+- SP (stack pointer, 8-bit hex)
+- PC (program counter, 16-bit hex)
+
+**FLAGS section:**
+- Individual status flags: N (Negative), V (Overflow), B (Break), D (Decimal), I (Interrupt Disable), Z (Zero), C (Carry)
+- Active flags are visually highlighted
+
+**TIMING section:**
+- CYC: Total CPU cycles since reset
+- Scanline and horizontal position (beam position)
+
+Changed register values are highlighted to show what was modified by the last instruction.
+
+### Disassembly View
+
+The disassembly panel shows a scrollable view of decoded 65C02 instructions centered around the current PC. Features include:
+
+- Addresses with symbol annotations from the built-in symbol table
+- Operand values resolved to known symbol names (soft switches, ROM routines, zero page locations)
+- Color-coded symbol categories (zero page, soft switches, disk, ROM, BASIC, vectors, I/O)
+- Current instruction highlighted
+- Breakpoint markers in the gutter (click to toggle)
+- Address bookmarks for quick navigation
+- Profile heat overlay (optional) showing instruction execution frequency
+
+The view can be navigated by clicking addresses or using the address input to jump to any location. When a disassembly view address is set manually, it overrides the PC-centered default.
+
+### Breakpoints
+
+Execution breakpoints pause the emulator when the program counter reaches a specified address. The `BreakpointManager` provides:
+
+| Feature | Description |
+|---------|-------------|
+| Address breakpoints | Break at a specific PC address |
+| Range breakpoints | Break anywhere within an address range (start to end) |
+| Conditional breakpoints | Break only when a C-style condition expression evaluates to true |
+| Hit count targets | Break only after the Nth hit |
+| Enable/disable | Toggle breakpoints without removing them |
+| Temporary breakpoints | Used internally for Step Over / Step Out |
+
+Breakpoints are persisted to localStorage (`a2e-breakpoints-v2`) and synchronized with the WASM module. Conditional breakpoints use the C++ condition evaluator (`src/core/debug/`) that supports register references (`A`, `X`, `Y`, `PC`, `SP`, `P`), memory reads (`[addr]`, `[addr,16]`), arithmetic operators, and logical combinators.
+
+### Watchpoints
+
+Watchpoints monitor memory access at specific addresses:
+
+| Type | Trigger |
+|------|---------|
+| Read | Breaks when the address is read |
+| Write | Breaks when the address is written |
+| Read/Write | Breaks on either access type |
+
+Watchpoints support the same conditional expressions as breakpoints. They are managed through the same `BreakpointManager` with a `type` field distinguishing them from execution breakpoints.
+
+### Watch Expressions
+
+The Watch panel allows arbitrary C-style expressions to be evaluated on each pause/step. Expressions can reference:
+
+- CPU registers: `A`, `X`, `Y`, `SP`, `PC`, `P`
+- Memory reads: `[address]` for 8-bit, `[address,16]` for 16-bit
+- Arithmetic: `+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `~`, `<<`, `>>`
+- Comparison: `==`, `!=`, `<`, `>`, `<=`, `>=`
+
+Watch values are displayed with change highlighting when values differ from the previous evaluation.
+
+### Beam Breakpoints
+
+Beam breakpoints pause execution at a specific video scanline and optional horizontal position. This is useful for debugging video timing-sensitive code. Each beam breakpoint has:
+
+- Scanline number (0-261)
+- Horizontal position (optional)
+- Enable/disable toggle
+- Mode selection
+
+### Bookmarks
+
+Address bookmarks provide quick navigation to frequently visited code locations. Bookmarks are shown as markers in the disassembly gutter and stored in localStorage.
+
+### Symbol Resolution
+
+The built-in symbol table (`symbols.js`) provides names and descriptions for hundreds of Apple IIe addresses across categories:
+
+| Category | Examples |
+|----------|---------|
+| Zero Page | LOMEM, WNDLFT, CH, CV, BASL, TXTTAB, VARTAB |
+| Soft Switches | TEXT, MIXED, PAGE2, HIRES, 80COL, DHIRES |
+| ROM Routines | COUT, RDKEY, HOME, PRBYTE, INIT |
+| Disk | RWTS, IOB, DOS entry points |
+| BASIC | Token handler addresses |
+| Vectors | RESET, IRQ, NMI, BRK |
+| I/O | Keyboard, speaker, game I/O |
+
+Symbols are color-coded by category in the disassembly view.
+
+### User Labels
+
+The `LabelManager` allows users to define custom labels and inline comments for any address. User labels override or supplement the built-in symbol table. Imported symbol files (from assemblers) are also supported. Labels persist to localStorage (`a2e-user-labels`).
+
+---
+
+## Memory Browser
+
+The Memory Browser (`memory-browser-window.js`) provides a scrollable hex/ASCII view of the full 64 KB address space.
+
+**Features:**
+- 16 bytes per row with address, hex values, and ASCII representation
+- Quick-jump buttons for common regions: Zero Page, Stack, Text Pages, HiRes Pages, I/O, ROM, DOS, Vectors
+- Address input for direct navigation
+- Hex byte search (finds the next occurrence of a byte sequence)
+- Region indicator showing which memory area is currently visible
+- Change highlighting: modified bytes flash briefly after they change
+- Scroll wheel navigation
+
+**Memory regions recognized:**
+
+| Region | Address Range |
+|--------|--------------|
+| Zero Page | `$0000-$00FF` |
+| Stack | `$0100-$01FF` |
+| Input Buffer | `$0200-$02FF` |
+| Text Page 1 | `$0400-$07FF` |
+| Text Page 2 | `$0800-$0BFF` |
+| HiRes Page 1 | `$2000-$3FFF` |
+| HiRes Page 2 | `$4000-$5FFF` |
+| DOS 3.3 | `$9600-$BFFF` |
+| I/O Space | `$C000-$C0FF` |
+| Slot ROMs | `$C100-$CFFF` |
+| ROM / LC RAM | `$D000-$FFFF` |
+
+---
+
+## Memory Heat Map
+
+The Memory Heat Map (`memory-heat-map-window.js`) provides a real-time visualization of memory access patterns using canvas-based rendering.
+
+**Features:**
+- Dual-panel display: Main memory (64 KB) and Auxiliary memory (64 KB)
+- Three view modes: Combined (reads + writes), Reads Only, Writes Only
+- Optional decay mode: hot spots fade over time instead of accumulating
+- Start/Stop/Clear controls for tracking
+- Hover tooltip showing the address and region under the cursor
+- Click to jump to address in Memory Browser (when connected)
+
+Each pixel in the heat map represents a small block of addresses. Color intensity indicates access frequency: brighter colors indicate more frequent access.
+
+**Region labels are shown for both main and auxiliary memory**, with standard Apple IIe memory regions (Zero Page, Stack, Text Pages, HiRes Pages, etc.) and auxiliary equivalents.
+
+---
+
+## Memory Map
+
+The Memory Map (`memory-map-window.js`) shows the current memory bank configuration at a glance. It displays a visual representation of which memory banks (Main vs Auxiliary) are active for each address range, driven by the current soft switch states.
+
+The map shows bank switching for:
+- Zero Page / Stack (`$0000-$01FF`)
+- Text Page 1 (`$0400-$07FF`)
+- HiRes Page 1 (`$2000-$3FFF`)
+- HiRes Page 2 (`$4000-$5FFF`)
+- RAM / ROM regions (`$C000-$FFFF`)
+- Language Card bank configuration
+
+Active banks are highlighted while inactive banks are dimmed.
+
+---
+
+## Stack Viewer
+
+The Stack Viewer (`stack-viewer-window.js`) displays the current contents of the 6502 stack (page `$01xx`).
+
+**Features:**
+- Stack pointer value and depth indicator with visual fill bar
+- Call stack reconstruction: identifies JSR return addresses on the stack (6502 pushes PC+2-1, so return addresses are adjusted by +1)
+- Per-entry display: address, hex value, and analysis (e.g., "RTS to $XXXX" for detected return addresses)
+- Previous SP tracking for highlighting stack changes
+- Scroll to current stack pointer position
+
+---
+
+## Zero Page Watch
+
+The Zero Page Watch (`zero-page-watch-window.js`) monitors specific zero page locations with predefined and custom watch groups.
+
+**Predefined watch groups:**
+
+| Group | Locations |
+|-------|-----------|
+| BASIC Pointers | TXTTAB, VARTAB, ARYTAB, STREND, FRETOP, MEMSIZ, CURLIN, TXTPTR |
+| Screen/Window | WNDLFT, WNDWDTH, WNDTOP, WNDBTM, CH, CV, BASL, BAS2L |
+| Graphics | GBASL, COLOR, HCOLOR1, HGRX, HGRY |
+| DOS 3.3 | DOSSLOT, DOSDRIVE, FILTYP |
+| System | LOC0, LOC2, CSWL, KSWL, A1L, A2L, A4L, ACC, XREG, YREG, STATUS |
+
+**Features:**
+- Collapsible groups with expand/collapse state persistence
+- 8-bit and 16-bit value display
+- Custom watches: add any zero page address with a custom label
+- Change highlighting with fade-out animation
+- Description tooltips for each location
+
+---
+
+## Soft Switch Monitor
+
+The Soft Switch Monitor (`soft-switch-window.js`) displays the state of all Apple IIe soft switches organized by function.
+
+**Switch groups:**
+
+| Group | Switches |
+|-------|----------|
+| Display Mode | TEXT, MIXED, PAGE2, HIRES, 80COL, ALTCHAR, DHIRES |
+| Memory Banking | RAMRD, RAMWRT, ALTZP, 80STORE, INTCXROM, SLOTC3ROM |
+| Language Card | LCRAM, LCWRT, LCBNK2 |
+
+Each switch shows:
+- Name and current state (ON/OFF)
+- Toggle address(es) (e.g., `$C050/51`)
+- Brief description
+- Active state highlighted with color
+
+The display updates in real-time as switches change during emulation.
+
+---
+
+## Mockingboard Debug
+
+The Mockingboard window (`mockingboard-window.js`) provides a unified channel-centric view of both AY-3-8910 PSGs and their VIA 6522 controllers.
+
+**Channel cards** (6 total: PSG1 A/B/C, PSG2 A/B/C):
+- Tone period and computed frequency with musical note name
+- Volume level (0-15) with visual level meter
+- Mixer state (tone enable, noise enable)
+- Envelope mode indicator with shape waveform SVG
+- Per-channel mute toggle
+- Real-time inline waveform display
+
+**VIA detail section:**
+- Timer 1 counter, latch, and mode (one-shot / free-running)
+- Timer 2 counter
+- ACR, IFR, IER register values
+- IRQ active state
+- Port A/B data and direction registers
+
+**Additional features:**
+- Frequency-to-note conversion (A4 = 440 Hz reference)
+- Envelope shape SVGs for all 16 shape values
+- Color-coded channel badges (A = blue, B = green, C = red)
+- Dirty checking for efficient DOM updates
+
+---
+
+## Mouse Card Debug
+
+The Mouse Card window (`mouse-card-window.js`) displays the state of the Apple Mouse Interface Card.
+
+**Sections:**
+- **Status:** Installation state and slot number
+- **Mouse State:** X/Y position, button state, interrupt flags
+- **Mode:** Enabled, movement tracking, button tracking, VBL interrupt
+- **PIA Registers:** MC6821 register values for the mouse protocol
+- **Protocol Activity:** Last command (SET, READ, SERV, CLEAR, POS, INIT, CLAMP, HOME), timing
+
+---
+
+## BASIC Program Window
+
+The BASIC Program Window (`basic-program-window.js`) combines a program editor with an integrated Applesoft BASIC debugger.
+
+### Editor
+
+- Syntax-highlighted source code editor with Applesoft BASIC token recognition
+- Autocomplete for BASIC keywords
+- Line number gutter with breakpoint markers
+- Direct loading of programs into emulator memory using tokenization
+- Import/export of BASIC source files
+
+### BASIC Debugger
+
+The debugger toolbar provides:
+- **Run:** Tokenize and load the program, then execute it
+- **Pause:** Break at the next BASIC line
+- **Step:** Execute one BASIC statement
+
+The debugger tracks execution state through zero page pointers:
+- `CURLIN` (`$75-$76`): Current BASIC line number being executed
+- `TXTPTR` (`$7A-$7B`): Pointer to current position in program text
+
+When paused, the currently executing line is highlighted in the editor. Statement-level stepping allows stepping through individual statements within a multi-statement line (statements separated by colons).
+
+### Variable Inspector
+
+The `BasicVariableInspector` reads BASIC variables directly from emulator memory:
+
+| Memory Region | Pointer | Contents |
+|---------------|---------|----------|
+| Simple variables | VARTAB (`$69`) to ARYTAB (`$6B`) | 7-byte entries (2-byte name + 5-byte value) |
+| Arrays | ARYTAB (`$6B`) to STREND (`$6D`) | Variable-length array entries |
+
+**Variable types detected:**
+- **Real:** 5-byte Applesoft floating point
+- **Integer:** 2-byte signed 16-bit (high byte first)
+- **String:** 1-byte length + 2-byte pointer to string data
+
+Variables display with change highlighting. Arrays can be expanded to show individual elements. Auto-refresh mode updates variables while the program is running.
+
+### BASIC Breakpoints
+
+The `BasicBreakpointManager` manages line-level breakpoints for BASIC programs. Breakpoints are set on BASIC line numbers (not memory addresses). The manager supports:
+
+- Line breakpoints with hit counters
+- Statement-level stepping mode
+- Synchronization with the WASM breakpoint interface
+- Persistence to localStorage (`a2e-basic-breakpoints`)
+
+The `BasicProgramParser` reads the tokenized program from memory starting at TXTTAB, parsing the linked list of lines (each line: 2-byte next pointer, 2-byte line number, tokenized text, null terminator).
+
+---
+
+## Rule Builder
+
+The Rule Builder (`rule-builder-window.js`) provides a visual interface for composing complex breakpoint conditions without writing condition expressions manually.
+
+**Features:**
+- Tree-based rule composition with AND/OR groups
+- Nested groups for complex logic
+- Operand types: registers (A, X, Y, SP, PC, P), memory reads, constants
+- Comparison operators: equals, not equals, less than, greater than, less/greater or equal
+- Bitwise operators for flag testing
+- Live preview of the generated condition expression
+- Apply/Cancel workflow that integrates with the CPU Debugger's breakpoint system
+
+The rule builder is opened from the CPU Debugger when editing a breakpoint's condition. The generated expression string is passed to the C++ condition evaluator for runtime evaluation.
+
+---
+
+## Assembler Editor
+
+The Assembler Editor (`assembler-editor-window.js`) provides a 65C02 assembly language editor with Merlin-style syntax support.
+
+**Editor features:**
+- Merlin-compatible column layout (label, opcode, operand, comment)
+- Syntax highlighting for 65C02 mnemonics, directives, labels, and comments
+- Real-time syntax validation with error markers in the gutter
+- Line numbers, cycle counts per instruction, and assembled byte display in the gutter
+- Expression evaluator for operands (arithmetic, symbols, `*` for current PC)
+- Breakpoint toggles per assembled line (F9)
+- Cursor position indicator showing line and column
+
+**Toolbar:**
+- New / Open / Save file operations
+- Assemble: assemble source to machine code with error reporting
+- Load: inject assembled code into emulator memory at the origin address
+- Example program loader
+- ROM Routines reference browser (searchable, categorized)
+
+**Assembly output:**
+- Per-line hex bytes and addresses
+- Symbol table from labels
+- Error display with line numbers
+- Status bar showing assembled size and origin
+
+---
+
+## Instruction Trace
+
+The Instruction Trace (`trace-panel.js`) displays a scrollable history of recently executed CPU instructions from a ring buffer maintained in WASM.
+
+**Features:**
+- Virtual scrolling for performance with large trace buffers
+- Each entry shows: address, opcode bytes, mnemonic, operand, symbol annotations
+- Cached opcode mnemonic table from the WASM disassembler
+- Auto-scroll to most recent instruction on pause
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| F5 | Run / Continue execution |
+| F10 | Step Over |
+| F11 | Step Into |
+| Shift+F11 | Step Out |
+
+See [[Keyboard Shortcuts]] for the complete shortcut reference.
+
+---
+
+## Source Files
+
+### Core Debug Windows
+
+| File | Description |
+|------|-------------|
+| `src/js/debug/cpu-debugger-window.js` | CPU registers, disassembly, breakpoints, stepping |
+| `src/js/debug/memory-browser-window.js` | Hex/ASCII memory viewer with search |
+| `src/js/debug/memory-heat-map-window.js` | Real-time memory access visualization |
+| `src/js/debug/memory-map-window.js` | Memory bank configuration overview |
+| `src/js/debug/stack-viewer-window.js` | Stack contents with call stack reconstruction |
+| `src/js/debug/zero-page-watch-window.js` | Zero page location monitoring |
+| `src/js/debug/soft-switch-window.js` | Soft switch state display |
+
+### Hardware Debug Windows
+
+| File | Description |
+|------|-------------|
+| `src/js/debug/mockingboard-window.js` | AY-3-8910 and VIA 6522 state display |
+| `src/js/debug/mouse-card-window.js` | Mouse card PIA and protocol state |
+
+### BASIC and Assembly
+
+| File | Description |
+|------|-------------|
+| `src/js/debug/basic-program-window.js` | BASIC editor with integrated debugger |
+| `src/js/debug/basic-breakpoint-manager.js` | BASIC line breakpoint management |
+| `src/js/debug/basic-variable-inspector.js` | BASIC variable memory reader |
+| `src/js/debug/basic-program-parser.js` | Tokenized BASIC program parser |
+| `src/js/debug/assembler-editor-window.js` | 65C02 assembler with Merlin syntax |
+
+### Supporting Modules
+
+| File | Description |
+|------|-------------|
+| `src/js/debug/breakpoint-manager.js` | CPU breakpoint and watchpoint management |
+| `src/js/debug/rule-builder-window.js` | Visual condition expression builder |
+| `src/js/debug/symbols.js` | Apple IIe address symbol table |
+| `src/js/debug/label-manager.js` | User-defined labels and imported symbols |
+| `src/js/debug/trace-panel.js` | CPU instruction execution trace |
+| `src/js/debug/index.js` | Debug subsystem module exports |
+
+### C++ Support
+
+| File | Description |
+|------|-------------|
+| `src/core/debug/` | Condition evaluator for breakpoint expressions |
+| `src/core/disassembler/` | 65C02 instruction disassembler |
+
+---
+
+See also: [[CPU Emulation]] | [[Memory System]] | [[Audio System]] | [[Keyboard Shortcuts]]

package/wiki/Disk-Drives.md

@@ -0,0 +1,161 @@
+# Disk Drives
+
+The Disk Drives window provides a visual interface for the emulated Disk II controller. Open it from **View > Disk Drives** in the toolbar.
+
+The Apple //e supported two floppy drives connected to the Disk II controller card in Slot 6. Each drive reads and writes 5.25-inch floppy disks with 35 tracks and 16 sectors per track.
+
+---
+
+## Table of Contents
+
+- [Supported Disk Formats](#supported-disk-formats)
+- [Loading a Disk](#loading-a-disk)
+- [Ejecting a Disk](#ejecting-a-disk)
+- [Blank Disks](#blank-disks)
+- [Recent Disks](#recent-disks)
+- [Disk Persistence](#disk-persistence)
+- [Drive Status Display](#drive-status-display)
+- [Surface Visualisation](#surface-visualisation)
+- [Detail Panel](#detail-panel)
+- [Drive Sounds](#drive-sounds)
+- [Drag and Drop](#drag-and-drop)
+- [Write Protection and Saving](#write-protection-and-saving)
+
+---
+
+## Supported Disk Formats
+
+The emulator accepts the following 5.25-inch disk image formats:
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| **DSK** | `.dsk` | Raw sector-order disk image (140KB). The most common format. Sectors are stored in DOS 3.3 logical order. |
+| **DO** | `.do` | Identical to DSK format. The extension explicitly indicates DOS 3.3 sector ordering. |
+| **PO** | `.po` | ProDOS-order disk image (140KB). Sectors are stored in ProDOS physical order. |
+| **NIB** | `.nib` | Nibblised disk image (232,960 bytes). Stores the raw GCR-encoded data as it appears on the disk surface, including sync bytes, address fields, and data fields. |
+| **WOZ** | `.woz` | Bit-level disk image with timing and metadata. The most accurate format, capable of representing copy-protected disks. Stores individual flux transitions. |
+
+The file input accepts all five extensions: `.dsk`, `.do`, `.po`, `.woz`, and `.nib`.
+
+## Loading a Disk
+
+There are three ways to insert a disk:
+
+1. **Insert button** -- Click the **Insert** button on a drive to open a file browser. Select a disk image file to load it into that drive.
+
+2. **Drag and drop** -- Drag a disk image file from your desktop onto the emulator screen. The file will be loaded into the first empty drive. If both drives are occupied, it replaces the disk in Drive 1.
+
+3. **Recent Disks** -- Click the **Recent** button to see a dropdown of previously loaded disks. Click an entry to reload it instantly (see [Recent Disks](#recent-disks)).
+
+When a disk is loaded, the drive displays the filename (with scrolling animation if the name is too long) and enables the Eject button.
+
+## Ejecting a Disk
+
+Click the **Eject** button on a drive to remove the disk. If the disk has been modified since it was loaded, a save dialog appears offering to save the changes before ejecting:
+
+- **Save** -- Opens the browser's file-save dialog with the current filename as the default. After saving (or cancelling the file picker), the disk is ejected.
+- **Don't Save** -- Ejects the disk immediately, discarding any unsaved modifications.
+- Press **Escape** to cancel the eject entirely and keep the disk inserted.
+
+After ejecting, the drive display resets to "No Disk" and the surface visualisation clears.
+
+## Blank Disks
+
+Click the **Blank** button to insert a fresh, empty 140KB DOS 3.3 disk image. This is useful for saving data from within the emulated Apple //e -- format the blank disk with DOS 3.3 `INIT` or ProDOS, then save files to it.
+
+## Recent Disks
+
+Each drive maintains its own list of recently used disk images. Click **Recent** on a drive to see a dropdown of previous disks:
+
+- Click a disk name to reload it into that drive.
+- Click **Clear Recent** at the bottom of the list to remove all entries for that drive.
+- Recent disks are stored in IndexedDB along with their full disk image data, so they survive browser restarts.
+
+## Disk Persistence
+
+Inserted disks are automatically saved to IndexedDB so they persist across browser sessions:
+
+- When you load a disk, its data is stored in IndexedDB keyed by drive number.
+- On the next page load, both drives are automatically restored to their previous state.
+- Ejecting a disk clears its persisted data for that drive.
+
+This is separate from the [[Save-States]] system, which captures the entire emulator state including disk contents and modifications.
+
+## Drive Status Display
+
+Each drive shows:
+
+| Element | Description |
+|---------|-------------|
+| **Disk name** | The filename of the currently inserted disk. Long names scroll horizontally. |
+| **Track indicator** | Shows the current head position as `T00` through `T34`. Highlighted in colour when the drive motor is on and this drive is selected. Displays `T--` when no disk is present. |
+
+## Surface Visualisation
+
+Each drive includes a real-time canvas rendering of the disk surface. This animated view shows:
+
+- **Rotating disk** -- The floppy disk spins at 300 RPM when the motor is active. When the motor turns off, the disk decelerates realistically before stopping.
+- **35 tracks** -- Concentric rings from the outer edge to just outside the centre hub. Each track corresponds to one of the 35 tracks on a 5.25-inch floppy.
+- **16 sectors** -- Radial lines divide the disk into 16 sectors, matching the Apple II's sector layout.
+- **Head position** -- A small indicator shows which quarter-track the drive head is currently positioned over.
+- **Track access heat map** -- Recently accessed tracks glow with a colour intensity proportional to access frequency. The heat decays over time, so you can see which areas of the disk are being read or written in real time.
+- **Write mode indicator** -- The head indicator changes appearance when the drive is in write mode.
+- **Sticker colour** -- Each inserted disk receives a randomly-assigned vintage label colour (cream, manila, pale green, pale blue, pink, yellow, lavender, or white) derived from a hash of the filename.
+- **Hub hole and reinforcement ring** -- The centre of the disk shows the large hub hole and the white reinforcement ring, matching the physical appearance of a 5.25-inch floppy.
+- **Index hole** -- A small hole in the hub ring area, used by the drive hardware to detect disk rotation.
+
+The surface visualisation can be hidden by clicking the **eye icon** in the window title bar. When hidden, the window switches to a compact mode showing only the controls and status indicators.
+
+## Detail Panel
+
+Click the **info icon** in the title bar to expand a technical detail panel below each drive. This shows low-level controller state updated in real time:
+
+| Field | Description |
+|-------|-------------|
+| **QTrack** | Quarter-track position (0-139). The Disk II controller positions the head in quarter-track increments. |
+| **Phase** | Current stepper motor phase. |
+| **Nibble** | Current nibble position within the track's data stream. |
+| **Motor** | Motor state: ON or OFF. |
+| **Mode** | Read or Write mode. |
+| **Byte** | The last byte read from or written to the disk (hex). Only shown for the currently selected drive. |
+
+## Drive Sounds
+
+The emulator synthesises realistic Disk II drive sounds using the Web Audio API. All drive sounds are controlled by the master volume slider and can be toggled on or off from the **Sound** popup in the toolbar.
+
+### Sound Layers
+
+**Seek / Step sound** -- A short mechanical click played each time the drive head moves to a new track. Synthesised from a combination of:
+- A sharp initial noise transient (the physical click)
+- A high-frequency metallic tick at ~2200 Hz
+- A higher harmonic at ~3800 Hz for metallic character
+- A lower body resonance at ~1200 Hz
+
+All components decay rapidly within 25ms, passed through a 6 kHz low-pass filter.
+
+**Motor sound** -- A continuous layered sound while the drive motor is spinning, composed of three layers:
+- **Motor hum** -- A 55 Hz sawtooth oscillator through a 129 Hz low-pass filter, producing the low-frequency rumble of the spindle motor.
+- **Mechanical whir** -- Band-passed noise centred at ~499 Hz, simulating the general mechanical noise of the drive mechanism.
+- **Disk swish** -- Band-passed noise at ~1917 Hz modulated by a ~2.7 Hz LFO, reproducing the rhythmic sound of the floppy disk rubbing against its jacket at 300 RPM (~5 rotations per second).
+
+When the motor stops, all layers fade out over 150ms to avoid audio clicks.
+
+### Sound Controls
+
+- **Volume slider** -- The main volume slider in the toolbar header scales all drive sounds proportionally.
+- **Mute toggle** -- The mute toggle silences all emulator audio including drive sounds.
+- **Drive Sounds toggle** -- A dedicated toggle in the Sound popup enables or disables drive sounds independently of the main speaker and Mockingboard audio.
+
+## Drag and Drop
+
+You can drag disk image files directly from your file manager onto the emulator screen:
+
+1. The monitor frame highlights to indicate it is ready to receive a drop.
+2. Drop the file to insert it into the first empty drive (Drive 1 checked first, then Drive 2).
+3. If both drives already have disks, the dropped file replaces Drive 1.
+
+## Write Protection and Saving
+
+When ejecting a modified disk, the emulator prompts to save changes. The save dialog uses the browser's File System Access API (where available) to let you choose a save location and filename. The default filename is the original disk image name.
+
+Disk modifications are also preserved in save states -- see [[Save-States]] for details.