# Hauki OS - Bare-Metal JavaScript Architecture

## Overview
Hauki OS is an experimental operating system that boots natively on x86
hardware, embedding the Fabrice Bellard's MQuickJS engine directly at Ring 0.
By minimizing the C kernel to a mere bootstrapper and event loop, it allows
the entire OS logic, hardware drivers, and user interface to be implemented in
pure, elegant JavaScript.

## 1. Boot Sequence (BIOS to JS Engine)
1. **BIOS / Bootloader (`boot.s`):** The system boots via standard BIOS
(SeaBIOS in QEMU), loading a minimal Multiboot-compliant assembly stub. It
sets up a 16KB stack and hands control to the C kernel.
2. **C Kernel Initialization (`kernel_js.c`):**
   - Initializes the FPU (Floating Point Unit), essential for the JS engine's
math operations.
   - Configures the COM1 Serial Port (`0x3F8`) for headless debugging and
telemetry.
   - Allocates a contiguous 4MB block of zeroed memory (`raw_js_memory_buffer`)
 to serve as the JS Engine's Heap.
3. **MQuickJS Bootstrapping:**
   - Calls `JS_NewContext()` to spin up the JS virtual machine within the
allocated memory.
   - Injects the hardware bindings (temporarily by hijacking standard
functions like `setTimeout`).
   - Uses `JS_Eval()` to compile and execute the core OS script
(`system_js_code`), which initializes the shell (`HSH`) and returns a hardware
event closure to C.
4. **The Event Loop:** 
   - The C kernel drops into an infinite `while(1)` polling loop, watching the
PS/2 keyboard port (`0x60`).
   - On keypress, the scancode is pushed onto the JS stack via `JS_PushArg()`,
and the JS closure is invoked via `JS_Call()`.

## 2. Shell Architecture (HSH)
Currently, the Hauki Shell (HSH) is a monolithic JS object acting as a
reactive event consumer:
- **State Management:** Tracks `x` and `y` cursor coordinates, current text
color (`col`), and the input buffer (`buf`).
- **Rendering:** Contains logic for 80x25 VGA line wrapping and screen
clearing. It invokes the hardware abstraction layer to paint characters.
- **Input Handling:** Maps raw x86 scancodes to ASCII characters, mutating the
buffer and printing the echo.
- **Execution:** On pressing ENTER (`0x1C`), the `exec()` function evaluates
the buffer.

## 3. Hardware Abstractions (C-to-JS Bindings)
MQuickJS is heavily optimized for ROM-based microcontrollers, making dynamic
C-function registration difficult without modifying the build tools. 

**Current Methodology (Function Hijacking):**
We temporarily override built-in MQuickJS functions within `kernel_js.c` to
act as hardware interfaces:
- `sys.vga_write` -> Hijacks `setTimeout(x, y, char, color)`. Calculates
physical VGA offset and writes directly to physical address `0xB8000`.
- `sys.vga_clear` -> Hijacks `clearTimeout()`. Fills the 4000-byte VGA memory
with spaces.
- `sys.serial` -> Hijacks `print(str)`. Writes strings to the COM1 serial
port.

## 4. Roadmap & Future Possibilities
With JS execution successfully bridged to bare metal, the architecture will
evolve into the following structural milestones:

### A. The Dynamic REPL (Chrome Console & IRC Commands)
The static `exec` function will be transformed into a dynamic REPL:
- **Commands:** Inputs starting with `/` (e.g., `/color`, `/lspci`) will hit a
dynamic registry (`HSH.cmds`), allowing drivers to register their own OS
commands.
- **JS Evaluation:** Any other input will be passed through `eval()`. This
effectively turns the OS into a live JS IDE, allowing live variable
manipulation, mathematical evaluation, and live-coding directly on the VGA
terminal.

### B. The Clean Native Hardware API
The "hijack" methodology will be replaced. By modifying the `mquickjs_build.c`
generator, we will inject a clean `sys` namespace natively into the ROM table:
- `sys.inb(port)` and `sys.outb(port, val)` for raw Port I/O.
- `sys.mapPhysical(address, size)` for mapping physical memory into JS
TypedArrays.

### C. JavaScript Hardware Drivers
With raw Port I/O and Memory Mapping exposed, complex hardware logic can be
moved to JavaScript:
- **PCI Enumeration:** Scanning `0xCF8`/`0xCFC` ports purely with JS loops to
build an object tree of connected hardware.
- **Storage & VFS:** Writing an IDE/ATA PIO-mode driver in JS to read disk
sectors. Mounting a Virtual File System (`vfs.mounts['/']`) to load and
evaluate external `.js` driver files directly from the hard drive.