.cursorrules

# ACE-in-Browser: Design & Architecture

## Project Overview

Port **ACE Basic** — a recursive descent, peephole-optimising Amiga BASIC compiler
originally written by David Benn (1991–1996) — to run natively in a web browser.
Rather than emulating Amiga hardware, **simulate** the AmigaOS API surface that ACE
programs actually used, reimplementing it in JavaScript.

**Motivation:** reproduce what ACE did in as simple an environment as possible.
Why emulate if simulation will suffice? Prefer the smallest stack that runs real
ACE programs. Overly complex environments and solutions are rejected.

David Benn is the original author of ACE and is the primary developer of this project.

---

## Core Strategy

**Pure client-side JS:** a JavaScript compiler (grammar/semantics reverse-engineered
from the original recursive-descent C compiler, docs, and examples) emits readable
JavaScript. A JavaScript runtime implements the AmigaOS API surface ACE programs
depend on. The C ACE codebase is a **spec**, not the shipped toolchain.

The result: `.b` / `.bas` ACE source files compile and run in a browser with an
authentic Amiga look and feel.

This is NOT hardware emulation. It is API-level **simulation** at the AmigaOS layer.

### Host UX (non-negotiable)

- **Program picker** to load existing examples (and later user files)
- ACE source is **always visible** while a program runs
- ACE source is **always editable**; edit → compile → run is the normal loop
- Keep the UI minimal: picker, editor, run/stop, output/canvas

---

## Starting Point

- **Language / semantics reference**: original ACE docs + David Benn’s intent
- **Example programs**: [dbenn/ACE](https://github.com/dbenn/ACE) `prgs/` — written by
  David Benn for original ACE 2.4. Later forks that retain `prgs/` did not author them.
- **Parser/codegen reference**: original C sources in [dbenn/ACE](https://github.com/dbenn/ACE);
  [vidarh's Linux fork](https://github.com/vidarh/ACE) for Linux-port / retargeting notes
  (`parse*.c`, `codegen.c|h`) — reverse-engineer, do not ship
- All semantic authority rests with David Benn as original author — if anything
  is ambiguous, the original intent takes precedence over later forks

---

## Compiler: JS front-end (product path)

Implement a **JavaScript** lexer/parser/codegen that emits JavaScript calling the
runtime. Use the C recursive-descent compiler to recover grammar and edge cases;
use the Programmer’s Guide, Language Reference, and examples as the acceptance
oracle.

The C `gen_` taxonomy remains a useful **checklist** of constructs to cover, not
the implementation vehicle:

| Category | JS Backend Treatment |
|---|---|
| **68k housekeeping** | Register assignment, stack frames, calling conventions — likely **no-ops** in JS |
| **Control flow** | FOR/NEXT, WHILE/WEND, IF/THEN, GOTO, GOSUB — map to **JS control flow** |
| **AmigaOS API calls** | WINDOW, SCREEN, PRINT, PLAY, SAY etc — map to **JS runtime functions** |
| **I/O and string ops** | File I/O, string manipulation — map to **JS/IndexedDB equivalents** |

The high-level gen_ functions (closer to ACE constructs) are the most valuable —
they map almost directly to JS runtime calls. The low-level 68k housekeeping
gen_ functions are likely no-ops since JS manages its own memory and call stack.

### Output Format

The compiler emits **JavaScript source text** (not WASM). Rationale:
- AmigaOS API calls (Intuition, Graphics, Audio) all live in JS/DOM land —
  WASM cannot call these directly without JS glue anyway
- JS output is readable and debuggable in browser devtools
- ACE programs are not compute-bound; JS has enormous performance headroom
- Single-language stack: compiler output + runtime are both JS

---

## JS Runtime Layer

Reimplements the AmigaOS API surface that ACE programs actually used.
ACE programs called AmigaOS via shared libraries (bmap mechanism) rather than
banging hardware registers directly — this makes the API surface bounded and clear.

### Runtime Components

#### Intuition → Canvas-based UI
- Windows with Amiga-style title bars, depth/close/resize gadgets
- Menus (triggered by right mouse button)
- Requesters and alerts
- Topaz font (recreated as web font) throughout
- Workbench 2.0 colour palette (blue/grey/orange)
- Screen dragging behaviour

#### Graphics.library → Canvas 2D
- BitMap operations
- RastPort drawing (lines, rectangles, circles, flood fill)
- Planar → chunky conversion for any graphics assets
- Colour palette management

#### Paula (audio) → Web Audio API
- 4-channel sample playback
- Tracker/module music playback
- SOUND and WAVE commands

#### Speech → Web Speech API
- SAY command mapped to SpeechSynthesis
- Amiga-style voice parameters where possible

#### AmigaDOS → in-memory VFS (+ IndexedDB optional)
- Sequential file I/O (OPEN, CLOSE, INPUT#, PRINT#, WRITE#) when demos need it
- Prefer an in-memory named-blob store; IndexedDB only if persistence across reloads is wanted
- Directory operations / environment variables in JS as required

#### ACE Runtime Library (`db.lib` / `ami.lib` equivalents)
- Startup and shutdown scaffolding
- String handling
- Math functions
- Type coercion semantics faithful to ACE's original behaviour

### Input Devices
- **Keyboard**: full support
- **Mouse**: full support (pointer lock where needed)
- Joystick: out of scope

---

## AmigaOS UX Feel

A key goal is that programs feel like they're running on an Amiga:
- Topaz 8 / Topaz 11 font
- Workbench 1.3 or 2.0 window chrome
- Correct colour palette
- Intuition window behaviour (drag by title bar, depth arrangement)
- Right-mouse-button menu activation

---

## Example Programs (Acceptance Targets)

ACE ships with example programs in the distribution. These serve as the primary
acceptance test suite. A program "works" when it compiles via the modified ACE
and runs in the browser with behaviour equivalent to the original Amiga execution.

Source: David Benn's original ACE 2.4 distribution
([dbenn/ACE](https://github.com/dbenn/ACE) `prgs/`; mirrored under `examples/`)

---

## Development Phases (Suggested)

1. **Taxonomy** — catalogue all `gen_` functions, classify into the four categories above
2. **JS backend skeleton** — implement `codegen_js.c` with stubs for all gen_ functions,
   confirm compiler builds and emits JS scaffolding
3. **Control flow** — get loops, conditionals, GOTO/GOSUB working
4. **Console I/O** — PRINT, INPUT working in a simple terminal canvas
5. **Intuition basics** — WINDOW, SCREEN, basic drawing
6. **Audio** — SOUND, WAVE, PLAY
7. **Turtle + Gfx corpus** — turtle graphics, async SUBs/`spiro`, then `prgs/Gfx/`;
   defer `Turtle/bst.b` (STRUCT/pointer stack) until after Gfx
8. **Speech** — SAY
9. **Libraries / files as needed** — selective `LIBRARY` shims; in-memory VFS before IndexedDB
10. **Example programs running** — work through the remaining distribution examples

Authoritative ordering for agents: [`docs/implementation-plan.md`](docs/implementation-plan.md).

---

## Feature demos (in-repo)

Save screenshots and short screen recordings of new user-visible features under
`demos/<phase-or-feature>/` as you verify them (see [`demos/README.md`](demos/README.md)).
Do not leave walkthrough media only in ephemeral agent artifact storage — commit it
to the repo in the same PR when practical.

## Key Decisions Log

| Decision | Rationale |
|---|---|
| Simulation not emulation | ACE used AmigaOS APIs; hardware UAE is unnecessary complexity |
| Simplest environment that works | Abhor overly complex stacks; add layers only when forced by examples |
| JS compiler in-browser | Pure client-side; C ACE is a spec, not the product |
| JS output not WASM | DOM access from WASM requires JS glue anyway; JS is debuggable |
| Source always visible + editable | Load from picker, see ACE source, edit freely — core product loop |
| Demos in-repo under `demos/` | Keep feature screenshots/videos with the code for review and history |
| Canvas for Intuition | Natural mapping; gives authentic Amiga window chrome |
| IndexedDB for AmigaDOS | Persistent, async-friendly, browser-native — **optional**; prefer in-memory VFS until an example needs reload survival |
| Web Speech API for SAY | Direct equivalent; no custom synthesis needed |
| Turtle / Gfx before SAY & files | Visible ACE demos first; files are low value client-side |

---

## References

- Original ACE documentation: https://dbenn.github.io/docs/projects.html#ace
- Original ACE 2.4 (source + `prgs/` examples): https://github.com/dbenn/ACE
- vidarh's Linux fork (parser/codegen notes): https://github.com/vidarh/ACE
- ACE v2.3 Programmer's Guide: http://www.users.on.net/~dbenn/docs/ace.html