# 8088 Assembler

## About This App
A retro developer tool for writing and assembling Intel 8088 machine code in your browser



## Specification
# Intel 8088 Assembly Assembler

Create a retro-themed, fully functional Intel 8088 assembly language assembler web application that takes 8088 assembly source code as input and produces assembled machine code (hex bytes) as output, based on the complete 8088 instruction set provided.

## App Concept

This is an interactive, browser-based 8088 assembler — a love letter to the original IBM PC era. Users type assembly code in a code editor panel, click "Assemble," and see the resulting machine code bytes, memory layout, symbol table, and any errors. The aesthetic should evoke the feel of an early-80s CRT terminal: dark background, phosphor-green (or amber) monospace text, subtle scanline effects, and a chunky retro UI.

## UI Elements

### Header / Title Bar

- App title: **"8088 Assembler"** with a subtitle: *"Intel 8088 Instruction Set — Browser Edition"*
- A small blinking cursor or LED indicator for visual flair
- Styled like an old DOS program title bar — blocky, bold, retro font
- Optional: a tiny "8088" chip icon or ASCII art logo

### Main Layout — Two-Panel Split

The main content should be a **side-by-side split layout** (resizable or fixed 50/50) on desktop, stacking vertically on mobile:

#### Left Panel: Source Code Editor

- A large `<textarea>` or code editor area with monospace font (e.g., `Courier New`, `IBM Plex Mono`, or similar)
- Line numbers displayed in a gutter on the left side
- Syntax highlighting for:
  - **Instructions** (MOV, ADD, JMP, etc.) — bright green/cyan
  - **Registers** (AX, BX, CL, DS, etc.) — yellow/gold
  - **Numbers/Immediates** (0x1234, 0FFh, 42) — magenta/pink
  - **Labels** (loop:, start:, etc.) — white/bold
  - **Comments** (lines starting with `;`) — dim gray
  - **Directives** (ORG, DB, DW, EQU) — orange
- Placeholder text with a sample program:
  ```
  ; Hello 8088!
  ORG 0100h
  start:
      MOV AX, 1234h
      MOV BX, 5678h
      ADD AX, BX
      PUSH AX
      MOV CX, 10
  loop:
      DEC CX
      JNZ loop
      POP AX
      HLT
  ```
- Tab key should insert spaces (not change focus)
- Support for common number formats: hex (0FFh, 0xFF), decimal, binary (10101010b)

#### Right Panel: Output Area (Tabbed)

A tabbed output section with the following tabs:

1. **Hex Output** (default tab)
   - Shows the assembled bytes in a hex dump format:
     ```
     0100: B8 34 12 BB 78 56 01 D8  50 B9 0A 00 49 75 FD 58
     0110: F4
     ```
   - Address on the left, hex bytes in the middle, ASCII representation on the right (like a hex editor)
   - Highlight the bytes corresponding to the currently selected line in the editor

2. **Listing**
   - Traditional assembler listing showing address, bytes, and source side by side:
     ```
     0100  B8 34 12      MOV AX, 1234h
     0103  BB 78 56      MOV BX, 5678h
     0106  01 D8         ADD AX, BX
     0108  50            PUSH AX
     0109  B9 0A 00      MOV CX, 10
     010C  49            DEC CX
     010D  75 FD         JNZ loop
     010F  58            POP AX
     0110  F4            HLT
     ```

3. **Symbol Table**
   - Display all labels and their resolved addresses
   - EQU constants and their values
   - Formatted as a clean table

4. **Instruction Reference**
   - A searchable/filterable reference table of all 8088 instructions
   - Columns: Mnemonic, Opcode(s), Operands, Bytes, Cycles, Flags affected
   - Based on the complete opcode map provided
   - Clicking an instruction inserts it into the editor

### Toolbar / Action Bar

Between the header and the panels:

- **[▶ Assemble]** button — large, prominent, green/amber colored, triggers assembly
- **[Clear]** button — clears the editor
- **[Load Example ▼]** dropdown — preset example programs:
  - "Hello World" (simple MOV/ADD)
  - "Loop Counter" (DEC/JNZ loop)
  - "String Copy" (MOVSB with REP)
  - "Stack Operations" (PUSH/POP)
  - "Arithmetic" (MUL/DIV/IMUL/IDIV)
  - "Conditional Jumps" (all Jcc variants)
- **[Copy Hex]** button — copies assembled hex to clipboard
- **[Download .COM]** button — downloads assembled bytes as a raw .COM binary file
- **ORG offset** input — small numeric input to set the origin address (default: 0100h for .COM files)

### Error / Message Bar

- A bar below the toolbar (or at the bottom of the editor panel) that shows:
  - Success: "Assembly complete: 17 bytes generated" (green text)
  - Errors: "Line 5: Unknown instruction 'MOVX'" (red text, clickable to jump to line)
  - Warnings: "Line 8: Jump target out of range for rel8" (yellow text)
- Multiple errors should be listed, scrollable

### Footer

- Retro-styled footer with:
  - "Intel 8088 — The chip that started it all (1979)"
  - Byte count / instruction count stats
  - Link: `<a href="/remix">Remix on Berrry</a>`

## Styling Preferences

### Retro CRT Aesthetic

- **Background**: Very dark (#0a0a0a or #0d1117) — almost black
- **Text**: Phosphor green (#33ff33) or amber (#ffb000) — user toggle option
- **Font**: Monospace throughout — `"IBM Plex Mono", "Courier New", "Consolas", monospace`
- **Scanline effect**: Subtle CSS overlay with repeating horizontal lines at ~2px intervals, very low opacity
- **CRT glow**: Subtle text-shadow glow matching the text color (e.g., `text-shadow: 0 0 5px #33ff33`)
- **Borders**: 1px solid with the accent color, slightly rounded (2-4px radius max)
- **Buttons**: Blocky, uppercase text, border style rather than filled, with hover glow effects
- **Scrollbars**: Custom-styled to match the dark theme
- **Tab styling**: Underline-style active tab indicator

### Responsive Design

- On desktop (>1024px): Side-by-side panels
- On tablet (768-1024px): Stacked panels with collapsible sections
- On mobile (<768px): Single column, tabbed navigation between editor and output

## Functionality — The Assembler Engine

### Core Assembly Features (must implement):

1. **Two-pass assembly**:
   - Pass 1: Parse all labels, calculate addresses, build symbol table
   - Pass 2: Resolve forward references, encode all instructions

2. **Supported instruction encoding** (based on the provided opcode table):
   - **ALU operations**: ADD, OR, ADC, SBB, AND, SUB, XOR, CMP — all addressing modes
   - **MOV**: All variants (reg-reg, reg-mem, mem-reg, immediate, segment registers)
   - **INC/DEC**: Register and r/m forms
   - **PUSH/POP**: Registers, segment registers, memory
   - **Jumps**: All conditional jumps (Jcc rel8), JMP (rel8, rel16, far), CALL (rel16, far), RET/RETF
   - **Shifts/Rotates**: ROL, ROR, RCL, RCR, SHL/SAL, SHR, SAR — by 1 and by CL
   - **Multiply/Divide**: MUL, IMUL, DIV, IDIV
   - **String ops**: MOVSB, MOVSW, CMPSB, CMPSW, STOSB, STOSW, LODSB, LODSW, SCASB, SCASW
   - **Prefixes**: REP, REPE/REPZ, REPNE/REPNZ, LOCK, segment overrides (ES:, CS:, SS:, DS:)
   - **Control**: NOP, HLT, INT, INTO, IRET, CLI, STI, CLC, STC, CMC, CLD, STD
   - **Misc**: XCHG, LEA, LES, LDS, XLAT, CBW, CWD, LAHF, SAHF, PUSHF, POPF, AAA, AAS, AAM, AAD, DAA, DAS, TEST, NOT, NEG, IN, OUT, LOOP, LOOPZ, LOOPNZ, JCXZ, WAIT

3. **ModR/M byte encoding**:
   - Full implementation of the MOD/RM byte with all addressing modes
   - Direct addressing: `[1234h]`
   - Register indirect: `[BX]`, `[SI]`, `[DI]`
   - Based: `[BX+SI]`, `[BP+DI]`, etc.
   - With displacement: `[BX+5]`, `[BP+SI+100h]`
   - Register-to-register: All 8-bit and 16-bit registers

4. **Directives**:
   - `ORG` — set origin address
   - `DB` — define byte(s) (supports strings: `DB 'Hello', 0`)
   - `DW` — define word(s)
   - `EQU` — constant definition
   - Labels with colon: `myLabel:`

5. **Number formats**:
   - Hexadecimal: `0FFh`, `0xFF`, `0FFH`
   - Decimal: `255`
   - Binary: `11111111b`
   - Octal: `377o` or `377q`

6. **Expression support** (basic):
   - Simple arithmetic in operands: `MOV AX, label + 2`
   - `$` for current address (e.g., `JMP $`)
   - `OFFSET` keyword

### Error Handling

- Unknown/unsupported mnemonics
- Invalid operand combinations (e.g., `MOV CS, AX` should warn)
- Undefined labels
- Jump out of range (rel8 overflow)
- Duplicate labels
- Invalid number formats
- Missing operands

### Quality of Life Features

- **Auto-assemble on pause** (optional toggle) — assemble automatically after user stops typing for 500ms
- **Line highlighting** — clicking a hex dump line highlights the corresponding source line and vice versa
- **Persist code** — save the current editor content to localStorage so it survives page reloads
- **Keyboard shortcut**: Ctrl+Enter / Cmd+Enter to assemble
- **Export**: Download assembled bytes as a `.COM` file (raw binary starting at offset 0100h)

## Additional Fun Features

- A small animated 8088 chip ASCII art in the corner that "processes" when assembling (spinning/blinking)
- Cycle count estimation in the listing output (based on the cycle counts from the opcode table)
- Byte size indicator that updates in real-time: "Program size: 17 bytes / 65,280 bytes max"
- Easter egg: assembling `NOP NOP NOP NOP` shows a playful "That's a lot of nothing!" message
- Tooltip on hover over hex bytes showing the instruction mnemonic

## App Type

**React Web App** — This needs significant state management (editor content, assembled output, symbol tables, error lists, tab switching), complex parsing logic, and responsive interactive UI. React is the best fit.

## About Berrry
Berrry transforms your social media content into interactive web applications. Share a Twitter/X post or Reddit comment, and our AI creates a custom web app hosted at your own subdomain.

**Visit**: https://berrry.app

Transform your social media ideas into real web applications today.