# 8088 Assembler

## About This App
A developer tool for writing and assembling Intel 8088 assembly code with real-time hex output and retro CRT aesthetics



## Specification
# Intel 8088 Assembly Assembler — with Hello World Example

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
- **Do NOT place any example code or hello world text in the header — the header is purely for branding/title**

### 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, INT, etc.) — bright green/cyan
  - **Registers** (AX, BX, CL, DS, DX, AH, etc.) — yellow/gold
  - **Numbers/Immediates** (0x1234, 0FFh, 42) — magenta/pink
  - **Labels** (loop:, start:, msg:, etc.) — white/bold
  - **Comments** (lines starting with `;`) — dim gray
  - **Directives** (ORG, DB, DW, EQU) — orange
  - **Strings** ('Hello, World!', etc.) — a distinct color like light cyan or light magenta
- **Default placeholder/initial code must be a DOS "Hello, World!" program** that uses INT 21h to print text:
  ```asm
  ; Hello, World! for DOS (.COM file)
  ; Prints "Hello, World!" using INT 21h
  ORG 0100h

  start:
      MOV AH, 09h        ; DOS print string function
      MOV DX, msg         ; Pointer to message string
      INT 21h             ; Call DOS interrupt
      MOV AH, 4Ch        ; DOS terminate program function
      INT 21h             ; Exit to DOS

  msg:
      DB 'Hello, World!$' ; '$' terminated string for INT 21h
  ```
- This hello world example should be the **default code loaded on first visit** and also available in the examples dropdown
- 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: B4 09 BA 0B 01 CD 21 B4  4C CD 21 48 65 6C 6C 6F
     0110: 2C 20 57 6F 72 6C 64 21  24
     ```
   - 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  B4 09         MOV AH, 09h
     0102  BA 0B 01      MOV DX, msg
     0105  CD 21         INT 21h
     0107  B4 4C         MOV AH, 4Ch
     0109  CD 21         INT 21h
     010B  48 65 6C 6C 6F 2C 20 57 6F 72 6C 64 21 24  DB 'Hello, World!$'
     ```

3. **Symbol Table**
   - Display all labels and their resolved addresses
   - EQU constants and their values
   - Formatted as a clean table
   - For the hello world example, should show: `start: 0100h`, `msg: 010Bh`

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!"** (the default — prints "Hello, World!" via INT 21h, should be the **first and default option**)
  - "Simple Math" (MOV/ADD/SUB operations)
  - "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: 25 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, World!$'`)
   - `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)
- **The Hello World example should be pre-loaded and auto-assembled on first load** so the user immediately sees a working example with output in all tabs

## 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: 25 bytes / 65,280 bytes max"
- Easter egg: assembling `NOP NOP NOP NOP` shows a playful "That's a lot of nothing!" message
- Easter egg: assembling the Hello World example shows a brief "Welcome to the 8088! 👋" toast message on first assembly
- 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.