retrotick: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

RetroTick is a browser-based x86 emulator that runs classic Windows PE/NE/MZ executables. Built with Preact + Vite + TypeScript + Tailwind CSS.

Commands

• npm run build — Production build to dist/
• npm run check — Alias for npm run build (catches type errors and regressions)
• timeout 2 npx tsx tests/test-<name>.mjs — Run a headless test for a specific exe

No test runner or linter scripts are configured.

Architecture

Core Layers

PE/NE Parsing (src/lib/pe/): Binary parsing of Windows executables. parse.ts handles PE header parsing and resource directory tree walking. Each extract-*.ts file handles one resource type (bitmap, icon, cursor, dialog, menu, string, version, accelerator, AVI, WAV, manifest, Delphi DFM, imports, exports). decode-dib.ts handles DIB-to-image conversion. RVA-to-file-offset mapping converts virtual addresses to actual file positions.

x86 CPU (src/lib/emu/x86/): Modular instruction execution:

• cpu.ts — CPU class with register accessors, flag get/set, push/pop, fetch, alu(), testCC()
• flags.ts — materializeFlags() for lazy flag evaluation
• lazy-op.ts — Lazy operation type definitions
• decode.ts — ModRM/SIB decoding, segment override, writeModRM
• dispatch.ts — Main instruction dispatch switch
• ops-0f.ts — Two-byte 0F opcode handler (Jcc/SETcc/CMOVcc/MOVZX/MOVSX/IMUL)
• ops-0f-ext.ts — Extended 0F opcodes (BT/BSF/BSR/SHLD/SHRD/XADD/CMPXCHG/BSWAP/RDTSC)
• fpu.ts — FPU helpers (fpuPush/fpuPop/fpuST/fpuSetST) + dispatcher
• fpu-d8db.ts — FPU opcodes D8-DB
• fpu-dcdf.ts — FPU opcodes DC-DF
• shift.ts — Shift/rotate operations (SHL/SHR/SAR/ROL/ROR/RCL/RCR/SHLD/SHRD)
• string.ts — String instructions (REP MOVS/STOS/CMPS/SCAS/LODS)

Emulator Core (src/lib/emu/):

• memory.ts — Linear 32-bit address space with segment translation and ANSI code page support
• emulator.ts — Emulator class with fields, heap/virtual alloc, arg reading, timer mgmt, delegates; ApiDef, Win32Dll, Win16Module for unified API registration
• thread.ts — Thread state management
• pe-loader.ts / ne-loader.ts / mz-loader.ts — Load PE32, NE (16-bit), and MZ (DOS) executables into memory
• emu-exec.ts — tick(), callWndProc(), callWndProc16(), completeThunk(), resume()
• emu-load.ts — load() and findResourceEntry()
• emu-thunks-pe.ts — Win32 thunk table builder, IAT verification, TEB init
• emu-thunks-ne.ts — Win16 thunk table builder, resource string reader
• emu-render.ts — fillTextBitmap, renderChildControls, sendDrawItem
• emu-render-controls.ts — renderButton, renderStatic, renderEdit
• emu-window.ts — DC management, canvas setup, SEH dispatch, resource loading
• dos-int.ts — DOS INT 21h interrupt services for MZ executables
• file-manager.ts — Virtual filesystem backed by IndexedDB
• cp437.ts — CP437 (DOS) character encoding table
• format.ts — Formatting utilities