nescript/docs/future-work.md

# Future Work

This document tracks the gaps between what NEScript currently compiles and
what the spec describes. Items are grouped by area. Anything implemented and
tested is omitted — `git log` is the authoritative record of what shipped.

---

## PNG-sourced palette and nametable assets

**What ships today.** `palette Name { colors: [...] }` and
`background Name { tiles: [...], attributes: [...] }` declarations with
inline byte arrays. The first declared palette / background is loaded
at reset time (before rendering enables), and both blocks get named
data blobs in PRG ROM so `set_palette Name` / `load_background Name`
can queue a vblank-safe swap via the NMI handler. See
`examples/palette_and_background.ne`.

**Still TODO.**
- `@palette("file.png")` — analyze image colours and map to nearest
  NES master-palette indices. `nearest_nes_color()` already lives in
  `src/assets/palette.rs` but is not wired through the resolver.
- `@nametable("file.png")` — convert a 256×240 image into a 960-byte
  nametable plus 64-byte attribute table with automatic tile
  deduplication (max 256 unique tiles per pattern table).
- Per-state background rendering control — programs currently get a
  single fixed nametable at reset; per-state swaps work but are
  limited by the NMI-time write budget (~2273 cycles, enough for a
  palette but not a full 1024-byte nametable).
- `--memory-map` should report palette and background PRG ROM usage
  alongside the variable layout.

---

## User code distribution across switchable banks

**Status.** `mapper: MMC1 / UxROM / MMC3` plus top-level `bank Name { prg }`
declarations are honored by the iNES header and by the linker, which reserves
each declared bank as a 16 KB switchable slot. However, the IR codegen puts
every user function and state handler into the fixed bank at `$C000-$FFFF` —
the declared banks exist only as empty space. Programs outgrowing the fixed
16 KB have nowhere to put their code.

**What's needed.**
- A bank-assignment step (analyzer or a new pass) that maps each user function
  / state handler to a target bank, either via explicit `bank Foo { fun bar()
  ... }` nesting or by greedy size-packing.
- Codegen support for emitting into non-fixed banks and for generating
  cross-bank trampolines (the runtime helper scaffold already exists in
  `runtime/mod.rs::gen_bank_trampoline`; it just isn't invoked).
- Linker changes so that functions in a switchable bank are found by the
  JSR fix-up logic when the call crosses bank boundaries.

---

## Language feature gaps (post-v0.1)

From the spec's "Reserved for Future Versions" section:

| Feature            | Description                                                           |
|--------------------|-----------------------------------------------------------------------|
| **Fixed-point**    | `fixed8.8` type for sub-pixel movement with operator support.         |
| **Text / HUD**     | Font sheet declarations + layout system for scores, health, menus.   |
| **Metasprites**    | Multi-tile sprite groups with relative positioning.                   |
| **Tilemaps**       | Declarative level data with built-in collision queries.              |
| **SRAM / saves**   | Persistent storage declarations for battery-backed save data.        |
| **NES 2.0 header** | Extended iNES header format for additional metadata.                  |

### Struct / array field widths

Struct and array element types are currently restricted to the single-byte
primitives (`u8`, `i8`, `bool`). `u16`, nested struct fields, and array fields
are rejected with `E0201`. The analyzer's field-layout machinery needs to
grow multi-byte offsets, and IR lowering needs to treat wide fields as the
existing wide-var path already does for `u16` globals.

---

## Audio pipeline

**What ships today.** Frame-walking pulse driver with `sfx Name { duty, pitch,
volume }` and `music Name { duty, volume, repeat, notes }` blocks; builtin
effects and tracks; a 60-entry period table; `__audio_used` marker that
elides the whole subsystem when no program statement references it.

**Still TODO for richer audio.**
- Triangle / noise / DMC channels (today the driver only uses pulse 1 and
  pulse 2).
- Multi-channel tracker playback (one `notes` list per channel).
- `@sfx("file.nsf")` / `@music("file.ftm")` asset directives — neither the
  NSF nor the FamiTracker format is parsed yet.
- Per-note pitch changes within a sfx (currently `pitch` latches once at
  trigger time).

---

## Debug instrumentation

**What ships today.** `debug.log(...)` and `debug.assert(...)` lower to $4800
writes when `--debug` is passed, and are stripped entirely in release builds.

**Not yet implemented.**
- Mesen-compatible symbol export (`.mlb` / `.sym` files) — the CLI does not
  emit them, and the previous `DebugSymbols` helper was removed as dead code
  during cleanup.
- Source maps relating ROM addresses to source lines — the `SourceLoc`
  IR op exists but is not consumed by the linker or CLI.
- Array bounds checking in debug mode.
- Frame overrun detection (cycles-per-frame counting).
- `debug.overlay(x, y, text)` — needs the text/HUD subsystem above.

---

## Code quality / tooling

### Register allocator

All IR temps currently spill to a recycled zero-page slot (`$80-$FF`). The
peephole pass mops up the most obvious waste, but a real CFG-aware allocator
that holds short-lived temps in `A`/`X`/`Y` would cut a noticeable number of
LDA/STA pairs.

### Cross-block temp live-range analysis

The slot recycler is function-local per-block. Temps that flow across block
boundaries get a dedicated slot for the entire function, even if a later
block could reuse the slot.

### `--no-opt` flag

There is no way to disable the optimizer from the CLI. Adding one would make
optimizer-introduced bugs easier to bisect.

### Compilation benchmarks

Compilation is fast (<100 ms for every example today) but has no `cargo
bench` harness, so regressions would slip through.

### WASM build target

To build a browser IDE we would need to route file I/O through a trait so the
core pipeline works on `&str → Vec<u8>` without touching `std::fs`. Today the
parser's preprocess pass and the asset resolver read files directly.

---

## Error message polish

### Unused error codes

`ErrorCode` only defines codes that are actually emitted. Previously there
were placeholder variants (`E0202` invalid cast, `E0403` unreachable state)
marked `#[allow(dead_code)]`; those were removed during cleanup. If those
semantics come back, add the codes at that point.

### Missing diagnostics

- No warning for implicit-drop of a function return value (`my_fun()` at
  statement position when `my_fun` returns non-void).
- `W0102` ("loop without yield") is only emitted for bare `loop`, not for
  `while true` or `loop { if cond { continue } }`.
- No warning for `fast` variables that never justify the zero-page slot
  (could cross-reference access counts).
- No warning when a `palette` declaration has inconsistent "index 0" bytes
  across its eight sub-palettes. The NES hardware mirrors `$3F10/$3F14/
  $3F18/$3F1C` onto `$3F00/$3F04/$3F08/$3F0C`, so writing the full 32-byte
  blob sequentially causes the last four "sprite sub-palette 0" bytes to
  overwrite the background universal colour; the fix is a user-side
  convention (every sub-palette's first byte equals the chosen universal
  colour) but the analyzer doesn't warn when a declaration violates it.
  The mistake produced a solid-black screen in `examples/platformer.ne`
  until it was chased down by hand.

---

## Open design questions

1. **Inline asm label syntax.** `.label:` (ca65 style) vs `label:` (generic)?
   Today the inline-asm parser accepts `label:` but not `.label`; migrating
   would be cheap but would invalidate any copy-pasted ca65 fragments.
2. **Debug port address.** $4800 is conventional but not universal. Should
   we support multiple debug output methods?
3. **OAM allocation strategy.** Sequential allocation vs priority-based with
   automatic sprite cycling for the 8-per-scanline limit?
4. **Error recovery granularity.** How aggressively should the parser
   recover? More recovery means more errors per compile but also risks
   cascading false errors.