Horizon 4

Educational computer architecture project (4-bit memory / 16-bit registers) with its own assembly language, real assembler, and IDE-style simulator.

What this repository contains

horizon4 combines four main pieces:

• horizon4 architecture: ISA, registers, memory model, formats, and conventions.
• horizon4 Assembly language: syntax and rules for .h4 programs.
• horizon4asm: TypeScript assembler that translates .h4 into binary and listing outputs.
• horizon4 Studio: Electron + React app to edit, assemble, run, and trace programs.

Target workflow:

Write .h4 -> Assemble -> Run -> Inspect registers/memory/traces

Repository structure

• docs/: PRD, phase plans, and technical project documentation.
• horizon4asm/: TypeScript assembler CLI.
• horizon4-studio/: desktop interface (Electron + Vite + React).
• build/: assembly artifacts (binaries, listings, address tables).
• MARS-main/: study reference for assembler/simulator patterns.
• typed_*.asm, typed_*.h4, typed_*.lst, typed_*.bin: test and demo examples.

Requirements

• Node.js 18+ recommended
• npm 9+ recommended
• Windows, Linux, or macOS

On Windows, commands use npm.cmd internally where needed.

Quick start

1) Assembler (horizon4asm)

cd horizon4asm
npm install
npm run test

Assemble a program:

npm run assemble -- examples/ejercicio1.h4 --out build/ejercicio1.bin --listing build/ejercicio1.lst --addr-table build/ejercicio1.addr.md

If output paths are not provided, defaults are generated in build/ based on the input filename.

2) IDE / simulator (horizon4-studio)

cd horizon4-studio
npm install
npm run dev

The app launches horizon4 Studio with:

• .h4 editor
• Assemble, Run, Step, Pause, Stop, Reset actions
• listing, registers, memory, and symbols panels
• diagnostics, syscall console, and execution trace
• trace export to CSV

Studio and assembler integration

horizon4-studio calls horizon4asm for source assembly.
To use assembly features inside Studio, dependencies must be installed in both directories:

• horizon4asm/
• horizon4-studio/

Useful scripts

horizon4asm

• npm run assemble -- <file.h4> ...: assemble source code.
• npm run test: assembler self-test.
• npm run check: TypeScript type-check without emit.
• npm run build: TypeScript build.

horizon4-studio

• npm run dev: development mode.
• npm run test: test suite with Vitest.
• npm run build: Electron app build.

Key documentation

• docs/PRD_horizon4.md: complete product vision and phased plan.
• docs/mars-analysis/: MARS pattern analysis adapted to horizon4.

Current status

The repository already includes a functional base for:

• academic specification and planning
• working assembler CLI with examples
• functional Studio app for assemble/run and machine-state inspection