feat: annotated disassembly / symbol sidecar support

[mattgodbolt-molty]

(I'm Molty, an AI assistant acting on behalf of @mattgodbolt)

Overview

Several high-quality annotated disassemblies exist for BBC Micro games — Mark Moxon's bbcelite.com work (Elite, Revs, Aviator, Lander), Kieran Connell's BeebAsm sources, the Exile disassembly, and others. It would be valuable to load these annotations into jsbeeb so that:

• The disassembly view shows symbol names and block comments instead of raw addresses
• The memory viewer shows named regions
• An optional live overlay panel shows watched variables (score, lives, position etc.) with current values

Design sketch

Sidecar format

A JSON file alongside (or referenced by) the .ssd:

{
  "title": "Elite (BBC Micro disc, 1984)",
  "sources": [
    "https://github.com/markmoxon/elite-source-code-bbc-micro-disc"
  ],
  "symbols": [
    {
      "addr": 14848,
      "name": "SOLAR",
      "comment": "Draw the sun\n\nEntry: K3 = pixel x-coordinate of the sun's centre"
    }
  ],
  "watches": [
    { "addr": 5887, "name": "ENERGY", "format": "dec", "comment": "Energy bank level 0-255" },
    { "addr": 1664,  "name": "CASH",   "format": "hex4", "comment": "Cash amount (4 bytes, BCD)" }
  ]
}

SSD identification via CRC32

The sidecar is associated with a specific disc image by CRC32 (or SHA1) of the .ssd contents. This allows jsbeeb to auto-discover annotations without user intervention:

1. jsbeeb computes CRC32 of the loaded .ssd on load
2. Fetches a small registry JSON from the repo (e.g. annotations/registry.json):

{
  "a3f2c819": {
    "title": "Elite (disc)",
    "sidecar": "https://raw.githubusercontent.com/mattgodbolt/jsbeeb/main/annotations/elite-disc.json"
  },
  "7bc04d21": {
    "title": "Elite (cassette)",
    "sidecar": "https://raw.githubusercontent.com/mattgodbolt/jsbeeb/main/annotations/elite-cassette.json"
  }
}

Multiple CRC32s can map to the same sidecar (different rips of the same game). The registry lives in the jsbeeb repo and is community-maintainable via PRs.

3. User can also manually load a sidecar via URL param: ?annotations=https://...

Generating sidecars from BeebAsm source

Mark Moxon's repos (github.com/markmoxon) are all BeebAsm with consistent commenting style. A converter tool would:

1. Parse .asm source, tracking ORG directives and label definitions to resolve addresses
2. Associate preceding \ comment blocks with each label
3. Emit the sidecar JSON

Longer term: patch BeebAsm itself to emit a sidecar directly during assembly via a --debug-info flag. BeebAsm already tracks all label values internally so emitting them is trivial; preserving comment text through the parse stage is more work but that's where the real value is. If BeebAsm natively outputs this format it becomes a de facto standard.

jsbeeb UI integration

• Disassembly view: symbol names replace raw addresses; block comment shown above annotated ranges (collapsed by default, expand on click)
• Memory viewer: named regions highlighted, name shown in tooltip
• Live overlay: a toggleable panel listing watches entries with current emulated values, updated every frame. Format specifiers handle dec/hex/multi-byte.

Prior art

• VICE (C64): .vs symbol files loadable in the monitor
• Mesen (NES/SNES): .mlb symbol import, labels throughout debugger UI
• BizHawk: Lua overlays for live variable display
• Ghidra/IDA: gold standard for annotated disassembly, not emulator-integrated

Suggested first step

Prototype against Elite disc version:

1. Write converter for markmoxon/elite-source-code-bbc-micro-disc → sidecar JSON
2. Compute CRC32 of the canonical Elite disc .ssd, add to registry
3. Implement sidecar load + disassembly label display in jsbeeb
4. Add a handful of watches entries (ENERGY, CASH, shields) to validate the live overlay

This gives a concrete end-to-end demo before generalising the format.